Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@thincms-mcp create a new blog post titled 'My First Post'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP (Model Context Protocol) server for ThinCMS. Gives AI agents typed tool access to your ThinCMS site — no HTTP boilerplate, no header construction, no JSON encoding.
Wraps the ThinCMS REST API as 45 typed tools that any MCP-compatible AI client can call directly. Instead of constructing HTTP requests, agents call tools like thincms_create_post(title, content, status) and get structured responses back.
Related MCP server: hidrix-tools
Node.js 18+
A running ThinCMS instance
An API key from ThinCMS (Admin > API Keys)
An MCP-compatible client (Claude Desktop, Claude Code, VS Code, etc.)
Add to your claude_desktop_config.json:
{
"mcpServers": {
"thincms": {
"command": "npx",
"args": ["tsx", "/path/to/thincms-mcp/src/index.ts"],
"env": {
"THINCMS_BASE_URL": "https://your-domain.com",
"THINCMS_API_KEY": "tcms_your_key_here",
"THINCMS_SITE_ID": "your_site_id_here"
}
}
}
}Same configuration in .claude/settings.json or global Claude Code settings.
Group | Tools |
Posts |
|
Pages |
|
Categories |
|
Authors |
|
Tags |
|
Media |
|
Template |
|
Navigation |
|
Settings |
|
Scripts |
|
Secrets |
|
Forms |
|
Submissions |
|
Search |
|
Preview |
|
All tool names are prefixed with thincms_ (e.g., thincms_list_posts).
Uses the same API key auth as the REST API. API keys grant editor-level access — full CRUD on content, forms, templates, navigation, scripts, and secrets. Cannot change site settings, manage users, or run imports/backups.
npm install
npm run build # Compile TypeScript
npm run dev # Run with tsx (for development)MIT
Add a question to a quiz. Each question has 2-5 answer options and one correct answer identified by index (0-based).
| Name | Required | Description | Default |
|---|---|---|---|
| quizId | Yes | Quiz ID (required) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| options | Yes | Array of 2-5 answer option strings (required) | |
| sortOrder | No | Position within the quiz (auto-assigned if omitted) | |
| explanation | No | Explanation shown after answering (for show_answer mode) | |
| correctIndex | Yes | Index of the correct answer in the options array (0-based, required) | |
| questionText | Yes | The question text (required) | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It only mentions constraints on options and correctIndex, but fails to describe side effects, return value, permission requirements, or whether the question is appended at a given sortOrder.
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 a single, front-loaded sentence that immediately conveys the tool's purpose and key constraints. No unnecessary words.
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 8 parameters, no annotations, and no output schema, the description is incomplete. It omits details such as the behavior when sortOrder is omitted, response format, and whether the quiz must already exist. The description covers only high-level intent.
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 baseline is 3. The description adds minimal value beyond schema by restating constraints, but does not explain the meaning or usage of parameters like quizId, siteId, or confirmProductionWrite beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add') and resource ('question to a quiz'), and implies it creates new questions rather than updating or deleting, which differentiates it from siblings like thincms_update_quiz_question. However, it does not explicitly contrast with other tools.
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 provides no guidance on when to use this tool versus alternatives (e.g., thincms_create_quiz, thincms_update_quiz_question), nor any prerequisites or exclusions. This leaves the agent without contextual selection cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a step to a sequence.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| subject | Yes | Email subject | |
| delayDays | No | Days to wait after previous step (0 = immediate) | |
| sequenceId | Yes | Sequence ID | |
| htmlContent | Yes | Email HTML body | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits beyond the action. It does not state if the step is appended, inserted at a position, or if it is idempotent. The agent lacks information about side effects or success indicators.
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 very short (7 words) but lacks essential information. It is under-specified rather than efficiently informative. A good description would be concise but include context like order or prerequisites.
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 that this is a mutation tool with 6 parameters, no output schema, and no annotations, the description is inadequate. It does not explain the behavior of 'step' (e.g., position in sequence), nor what happens upon success. The presence of reorder tools suggests ordering matters, but this is unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The tool description adds no extra parameter meaning, but the schema itself is sufficient. Baseline 3 is appropriate since the schema compensates.
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 'Add a step to a sequence' clearly states the verb (add) and resource (step to a sequence). However, it does not differentiate from sibling tools like thincms_update_sequence_step or thincms_create_sequence, though the naming helps. The purpose is understandable but could be more specific about what constitutes a step.
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?
No guidance on when to use this tool versus alternatives. There is no mention of prerequisites (e.g., the sequence must exist, identified by sequenceId), nor any indication of when to use update vs add. The description provides no usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get top referrer domains for a given period.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max referrers to return (default: 10, max: 100) | |
| period | No | Time period (default: 30d) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states the purpose and does not disclose behavioral traits such as permissions, rate limits, or side effects. The presence of 'confirmProductionWrite' in the schema may cause confusion about read vs write nature, but the description does not clarify.
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 a single efficient sentence with no fluff. It could benefit from additional context but remains appropriately concise for a simple tool.
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 100% schema coverage, the description lacks completeness: it does not describe the return format (e.g., list of domains with counts), does not explain the use of the 'siteId' or 'confirmProductionWrite' parameters in context, and provides no behavioral context. The tool has no output schema, so the description should compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters, so baseline is 3. The description adds no additional meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get top referrer domains for a given period.' It uses a specific verb ('Get') and resource ('top referrer domains'), and distinguishes from sibling analytics tools which cover summary, top pages, and trends.
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 for referrer data but does not explicitly guide when to use this tool versus other analytics tools (e.g., thincms_analytics_summary, thincms_analytics_top_pages). No when-not or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get analytics summary: total views, unique visitors, top page, views today. Period: 7d, 30d, or 90d.
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | Time period (default: 30d) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It correctly implies a read-only operation ('Get') and lists the data returned. However, it does not disclose potential side effects, authorization requirements, or idempotency. For a simple read operation, the description is adequate but not exhaustive.
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 concise, consisting of two sentences that front-load the purpose and key parameters. It is efficient and free of unnecessary words, though it could be slightly more structured (e.g., separating period options explicitly).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the absence of an output schema, the description adequately covers the returned metrics and period options. It does not mention the optional siteId or confirmProductionWrite, but those are well-documented in the schema. Overall, the description is complete for a straightforward analytics summary tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description does not need to compensate heavily. It adds value by listing the metrics returned (not in schema) but does not elaborate on the period or siteId beyond what the schema descriptions already provide. The description is neutral; it neither adds nor detracts from 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?
The description clearly states the tool retrieves an analytics summary with specific metrics (total views, unique visitors, top page, views today) and period options (7d, 30d, 90d). The verb 'Get' and resource 'analytics summary' are precise, and it distinguishes from sibling analytics tools like thincms_analytics_top_pages and thincms_analytics_trend.
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 provides clear context on when to use the tool (to get summary analytics) but does not explicitly state when not to use it or compare it to sibling analytics tools. While the metrics listed help differentiate, it lacks explicit guidance on alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get top pages by views for a given period.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max pages to return (default: 10, max: 100) | |
| period | No | Time period (default: 30d) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral disclosure. It does not mention that this is a read-only operation or that the confirmProductionWrite parameter is likely irrelevant for this endpoint. It also omits details like pagination or state effects.
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?
Single sentence clearly conveys core purpose with no wasted words. However, it could be slightly more structured by separating purpose from usage hints.
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 description is too brief given the complexity of parameters like siteId and confirmProductionWrite. It does not hint at the return value structure (list of pages with views) or any limitations, leaving the agent with incomplete context.
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 schema already explains all parameters. The description adds minimal value beyond restating 'for a given period'. Baseline score of 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 clearly states the verb 'Get', the resource 'top pages', and the metric 'by views' for a given period. It distinguishes from sibling analytics tools like summary, referrers, and trend.
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?
No guidance on when to use this tool versus alternatives like thincms_analytics_summary or thincms_analytics_trend. It does not specify prerequisites or whether it is read-only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get daily views and visitors trend for a given period.
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | Time period (default: 30d) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read-only operation ('Get'), and the parameter descriptions for siteId and confirmProductionWrite add valuable context about state safety and when confirmProductionWrite applies. No annotations are provided, so the description partially compensates but does not address all behavioral aspects like rate limits or data freshness.
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 a single, clear sentence that immediately conveys the tool's purpose. No extraneous information, well-suited for quick scanning.
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?
While the description explains the core function, it lacks details about return format (no output schema), pagination, or data granularity. For a tool with no output schema and low complexity, this is acceptable but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The tool description does not add additional parameter semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Get), the resource (daily views and visitors trend), and the context (for a given period). It differentiates from sibling analytics tools by specifying a unique metric.
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?
No explicit guidance on when to use this tool versus alternatives like thincms_analytics_summary or thincms_analytics_top_pages. The purpose is implied by the description, but no exclusions or prerequisites are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append CSS to the end of the site's existing stylesheet without replacing it. Useful for adding new rules without re-sending the entire stylesheet.
| Name | Required | Description | Default |
|---|---|---|---|
| css | No | CSS to append | |
| dryRun | No | When true, return the size delta the change would produce without writing. Use to sanity-check large appends before committing. | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| cssFile | No | Local file path containing CSS to append. Use instead of css for large additions. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool appends (without replacing) but does not mention other behavioral traits such as write implications, permission requirements, rate limits, or side effects. The confirmProductionWrite parameter is documented in the schema but not highlighted in the description.
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 waste. Every word contributes to understanding the tool's action and value. No superfluous details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 well-documented parameters and no output schema, the description is mostly complete. It explains the core action and use case. Could be slightly improved by noting that it appends to the active site's stylesheet, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The description adds minimal value beyond the schema, primarily reinforcing the append semantic. Baseline of 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Append CSS' and the resource 'the site's existing stylesheet'. It explicitly contrasts with replacement ('without replacing it'), distinguishing it from sibling tools like thincms_patch_css. The use case 'adding new rules without re-sending the entire stylesheet' further clarifies its purpose.
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 when to use (for incremental CSS additions) but does not explicitly state when not to use or mention alternatives like thincms_patch_css. It provides adequate context for basic usage but lacks exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create up to 100 blog posts in a single request. Each post follows the same schema as thincms_create_post. Validation errors are reported per-item without failing the batch.
| Name | Required | Description | Default |
|---|---|---|---|
| posts | Yes | Array of post objects to create | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses batch size limit, per-item validation, and schema reuse, but omits details about idempotency, authentication, rate limits, or atomicity. Adequate but not thorough.
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 two sentences, immediately stating the core action and key behavioral trait. No redundant 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?
Parameters are well-documented, but no output schema is provided and the description does not specify the response format. For a bulk creation tool, the agent would benefit from knowing what is returned (e.g., list of IDs or errors). Somewhat incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for each parameter. The description adds context about schema equivalence to thincms_create_post, but does not significantly enhance understanding beyond 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?
The description clearly states the tool creates up to 100 blog posts in a single request, with a specific verb 'create' and resource 'posts'. It distinguishes from the sibling thincms_create_post by mentioning bulk capability and per-item validation error handling.
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 when creating multiple posts with partial success tolerance, but does not explicitly state when not to use it or provide alternative tools. However, the sibling list includes thincms_create_post, allowing AI inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get campaign performance statistics (sent, opens, clicks, unsubscribes).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Campaign ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states that it retrieves statistics but does not mention if it is read-only, requires authentication, has rate limits, or any side effects. This is insufficient for safe agent invocation.
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 a single, front-loaded sentence that conveys the core purpose without waste. However, it is very brief and could potentially include more detail without becoming verbose.
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 tool has no output schema and the description does not explain the return structure, pagination, or any error conditions. It also does not mention the need for an active site (implied by siteId parameter). Given the complexity of campaign stats, this omission reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with most parameters having adequate descriptions (siteId and confirmProductionWrite are detailed). The tool description does not add any additional meaning beyond the schema for parameters; it only lists metric names. Baseline is 3 due to high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets campaign performance statistics and lists example metrics (sent, opens, clicks, unsubscribes). It distinguishes from siblings like thincms_get_campaign which likely returns campaign details rather than statistics. However, it does not explicitly differentiate from other stats tools.
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?
No guidance is given on when to use this tool versus alternatives. There is no mention of prerequisites, when not to use it, or which sibling tools might be more appropriate for different contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect the running MCP wrapper: version, count of registered tools, and the live tool list. Use to detect when your MCP host has cached a stale tool surface — if the count or list doesn't match what you expect for the current wrapper version, restart your host (Claude Desktop / Claude Code / VS Code) so it re-handshakes with the wrapper.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It implies a read operation ('Inspect') but does not explicitly state that it is non-destructive, safe, or has no side effects. It also omits details like output format or whether it requires authentication.
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 succinct sentences: first states purpose, second gives a concrete use case with actionable advice. No filler words, every sentence 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?
Given zero parameters and no output schema, the description lists what the tool returns (version, count, tool list), which is sufficient for this simple tool. However, it could clarify that calling it has no side effects.
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?
There are zero parameters with 100% schema coverage. The description adds no parameter info, but none is needed. Baseline for no parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: inspect the running MCP wrapper for version, tool count, and live tool list. This is a specific verb-resource combination and distinguishes itself from all sibling tools which perform content management operations.
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 provides a specific use case: detecting stale tool caches and instructs to restart the host. While it gives clear when-to-use context, it does not explicitly mention when not to use or list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clear the drift flag on a review after the editor has reconciled the edit (e.g. they're satisfied the new text is fine). Resets driftFlag to 'none' and clears driftNotes; if the review was held as drift_pending, that hold is also cleared (so a previously published review re-appears on the widget).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Review ID. | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It details the state changes (resets driftFlag, clears driftNotes, clears hold) and the publishing effect. However, it does not disclose whether the operation is reversible, permission requirements, or side effects like notifications.
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 two sentences with no redundant information. It is front-loaded with the action and efficiently expands on effects. Every word adds value.
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 3 parameters, no output schema, and no annotations, the description explains the tool's purpose and effects well. It lacks information about the return value (e.g., whether it returns the updated review or a success status), which would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 3 parameters. The description adds no additional meaning beyond what the schema provides for each parameter. Baseline 3 is appropriate as the schema already does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool clears the drift flag on a review, specifying the post-reconciliation context and the exact effects (resets driftFlag, clears driftNotes, clears hold). It distinguishes from sibling tools like thincms_publish_review and thincms_unpublish_review by focusing on drift resolution.
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 provides a clear precondition ('after the editor has reconciled the edit'), but does not explicitly state when not to use the tool or mention alternatives. It is clear enough for an agent to infer appropriate use, but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new author profile with bio, avatar, and social links.
| Name | Required | Description | Default |
|---|---|---|---|
| bio | No | Author bio/description | |
| name | Yes | Author name (required) | |
| slug | No | URL slug (auto-generated from name if omitted) | |
| No | Author email | ||
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| social | No | Social links object, e.g. { twitter: '@handle', linkedin: 'url' } | |
| website | No | Author website URL | |
| avatarUrl | No | URL to avatar image | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the full burden of behavioral disclosure. It only states 'create' without mentioning side effects, idempotency, authentication needs, or what happens if an author with the same name already exists. The confirmProductionWrite parameter in the schema hints at safety concerns, but the description ignores it.
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 a single sentence with no wasted words. It is front-loaded with the action and resource. However, it could be slightly more informative without losing conciseness, e.g., noting that the response contains the created author object.
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 tool has 9 parameters and no output schema, yet the description is only one short sentence. It does not mention the return value, error handling, or how to use the siteId and confirmProductionWrite parameters. Given the complexity, the description is insufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so each parameter is already documented. The description mentions three fields ('bio, avatar, and social links') but adds no new meaning or usage context beyond the schema. It is minimally additive but not harmful, earning a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new author profile') and specifies key fields ('bio, avatar, and social links'). The verb and resource are explicit, and the tool is clearly distinct from sibling tools like thincms_update_author and thincms_delete_author.
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 provides no guidance on when to use this tool versus alternatives (e.g., thincms_update_author for modifying an existing author). There are no explicit when-to-use or when-not-to-use instructions, leaving the agent to infer from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a campaign record in ThinCMS. This stores the email content; it does NOT push to the connected mail platform (e.g. ActiveCampaign) or deliver to recipients. Use thincms_send_campaign as the second step.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Campaign name | |
| listId | No | Override default list ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| subject | Yes | Email subject line | |
| tagFilter | No | Only send to contacts with this tag | |
| htmlContent | Yes | Email HTML body | |
| scheduledAt | No | DEPRECATED — use scheduledFor. ISO 8601 timestamp. | |
| scheduledFor | No | When the campaign should be delivered. Pass "immediate" to push to the mail platform now, or an ISO 8601 timestamp at least 60 minutes in the future to schedule. Omitting this is currently allowed (legacy fallback) but DEPRECATED — Phase 3 will require it. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool stores email content but does not deliver, which is a key behavioral trait. However, it does not mention important details like the confirmProductionWrite flag or the deprecation of scheduledAt, but given the schema covers these, the description provides adequate core transparency. Without annotations, the description holds the burden and does well.
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 extremely concise: two sentences with zero wasted words. It front-loads the core purpose, then distinguishes from the sibling, and gives a clear usage hint. Every sentence 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?
Given the complexity (9 parameters, no output schema, no annotations), the description covers the essential context: what the tool does, what it does NOT do, and the appropriate next step. It lacks mention of the confirmProductionWrite requirement or return value, but these are partially covered in the schema. Overall, it is sufficiently complete for its role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with all parameters already well-documented in the schema. The description adds overarching context (store vs. send) but does not elaborate on individual parameter semantics beyond what the schema provides. Hence baseline score of 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 clearly states it creates a campaign record in ThinCMS and explicitly distinguishes it from sending the campaign to the mail platform, which is done by the sibling tool thincms_send_campaign. The verb 'create' plus the resource 'campaign record' makes the purpose 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 provides explicit guidance on when to use this tool (first step to store content) and when not to use it (does not push to mail platform). It directly names the alternative second step tool (thincms_send_campaign), which helps the agent decide the correct sequence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new category. Optionally nest it under a parent category for hierarchy.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Category name (required) | |
| slug | No | URL slug (auto-generated from name if omitted) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| parentId | No | Parent category ID for nesting | |
| sortOrder | No | Sort order (lower = first) | |
| description | No | Category description | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only mentions optional nesting, but does not cover side effects, permissions, rate limits, or state changes. This is insufficient for a creation 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?
The description is a single, efficient sentence with no wasted words. However, it sacrifices completeness for brevity, which is acceptable for a simple tool but limits informativeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters and no output schema, the description is too minimal. It does not explain return values, error conditions, or prerequisites like site context. The schema covers parameters, but the description lacks holistic context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all 7 parameters. The description adds no additional meaning beyond 'optionally nest it under a parent category', which matches the parentId parameter. 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 clearly states the verb 'Create' and the resource 'a new category', and adds optional nesting for hierarchy. This distinguishes it from sibling tools like update, delete, list categories.
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 for creating a category, but does not specify when not to use it (e.g., bulk creation or imports) or provide alternatives. No explicit usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new collection. Display modes: 'cards' (grid), 'carousel' (horizontal scroll), 'banner' (full-width rotating), 'list' (vertical stack), 'compact' (smaller grid). Embed with {{collection:slug}} in page frame or content.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Collection name | |
| slug | No | URL-safe slug (auto-generated from name if omitted) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| columns | No | Grid columns for cards/compact/carousel (default: 3) | |
| enabled | No | Whether the collection is active (default: true) | |
| maxItems | No | Max items to show, 0 = all (default: 0) | |
| showLink | No | Show item links (default: true) | |
| showImage | No | Show item images (default: true) | |
| showTitle | No | Show item titles (default: true) | |
| sortOrder | No | Sort order for listing (default: 0) | |
| schemaType | No | Schema.org type to auto-emit on pages that render this collection via {{collection:slug}}. 'faq' emits FAQPage JSON-LD using each item's title as the question and body as the answer. Default 'none'. | |
| showRating | No | Show item ratings (default: true) | |
| autoAdvance | No | Auto-advance carousel/banner (default: false) | |
| description | No | Internal description/note | |
| displayMode | No | Display mode (default: cards) | |
| showSubtitle | No | Show item subtitles (default: true) | |
| advanceInterval | No | Seconds between auto-advance slides (default: 5) | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must cover behavioral traits. It discloses mutation and mentions embedding but does not detail safety, permissions, rate limits, or return format. Adequate but not rich.
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?
Extremely concise: two sentences that are front-loaded with purpose and key features. Every word adds value with no 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?
Covers core concept but lacks mention of response format (no output schema), prerequisites (e.g., active site), or the impact of optional parameters. Adequate for a simple tool but could be more complete given 18 parameters.
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 thoroughly explains parameters. The description adds value by explaining display modes and embedding context, but does not elaborate on individual parameters beyond 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?
The description clearly states 'Create a new collection' and lists display modes and embedding, making the tool's purpose and resource explicit. It is distinct from siblings like update/delete collection.
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 basic usage context (display modes, embedding) but no explicit guidance on when to use this tool versus alternatives (e.g., when to update vs create) or when not to use it. Sibling guidance is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add an item to a collection. The 'body' field is required (main content, can be HTML). Other fields are optional and visibility depends on the collection's show* settings.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | Main content text or HTML (required) | |
| title | No | Item title (e.g., person name, product name) | |
| rating | No | Rating 1-5 (for reviews/testimonials) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| enabled | No | Whether item is visible (default: true) | |
| linkUrl | No | Link URL (product page, profile, etc.) | |
| imageUrl | No | Image URL (photo, product image, logo) | |
| linkText | No | Link button text (default: 'Learn more') | |
| subtitle | No | Subtitle (e.g., role, company, price) | |
| sortOrder | No | Sort order (auto-assigned to end if omitted) | |
| collectionId | Yes | Collection ID | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It notes that body is required and visibility depends on show* settings, but omits success/error behavior, return values, idempotency, or side effects.
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 wasted words. The first sentence states the purpose, the second adds crucial parameter context. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with 12 parameters and no output schema, the description is adequate but incomplete. It covers the core function and key behavioral nuance but lacks return value info and error handling. Schema covers param details.
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%, but the description adds value by explaining body can be HTML and that field visibility depends on collection settings, providing context beyond 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?
The description clearly states the action 'Add an item to a collection' with the specific verb 'Add' and resource, distinguishing it from siblings like update or delete.
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 for creating new items but does not explicitly differentiate from update or delete tools, nor does it provide when-not-to-use guidance or alternative tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new reusable content block. For type='html' (default) the content field holds raw HTML inserted wherever {{block:slug}} appears. For type='reviews-widget', the block renders the published Google reviews widget server-side with config options (maxReviews, displayMode, minRating, showDate, showAvatar). Edit once, updates everywhere.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Display name for the block | |
| slug | No | URL-safe slug (auto-generated from name if omitted) | |
| type | No | Block type. Default: 'html'. | |
| config | No | JSON config blob for typed widgets (e.g. reviews-widget: '{"maxReviews":5,"displayMode":"grid"}'). Ignored for type='html'. | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| content | No | HTML content (only used for type='html') | |
| enabled | No | Whether the block is active (default: true) | |
| sortOrder | No | Sort order for listing (default: 0) | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains behavior for both block types, mentions server-side rendering for reviews-widget, and notes 'Edit once, updates everywhere'. Could add return value or side effects.
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 sentences, no fluff, front-loaded purpose, efficient coverage of key details.
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 9 parameters and no output schema, description covers main behavior well. Missing explicit mention of return value or site context, but schema fills gaps. Could mention confirmProductionWrite.
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 has 100% coverage, but description adds significant context: explains how content field is used for html type, describes config options for reviews-widget, and notes auto-generation of slug. Adds value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new reusable content block' and explains the two types (html and reviews-widget) with specific details, distinguishing it from sibling tools like update or delete.
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 for creating blocks but does not explicitly state when to use this vs. alternatives like update_content_block, nor does it mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new course or community. Courses start as draft by default. Set courseType to 'community' for ongoing recording libraries (modules become topics, lessons become recordings, content sorts newest-first). Set accessMode to control enrollment: 'free' (open), 'invite' (admin enrolls learners), or 'purchase' (Stripe payment required).
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | URL slug (auto-generated from title if omitted) | |
| title | Yes | Course title (required) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| status | No | Course status (default: draft) | |
| summary | No | Short plain-text blurb for course catalog cards | |
| dripMode | No | Content drip mode (default: all-at-once). Ignored for communities. | |
| accessMode | No | How learners gain access (default: free) | |
| courseType | No | Type: 'course' (structured curriculum) or 'community' (ongoing recordings). Default: course. Communities default to all-at-once drip and sort recordings by date. | |
| description | No | Full HTML landing page content | |
| thumbnailUrl | No | Thumbnail image URL | |
| priceCurrency | No | Currency code (default: USD) | |
| showInCatalog | No | Show on public course catalog page (default: true) | |
| priceAmountCents | No | Price in cents (for purchase mode) | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses default draft status, community mode effects, and production write guard via confirmProductionWrite. Lacks mention of rate limits or authentication details, but covers key behavioral aspects.
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 concise sentences front-loaded with purpose and defaults. Every sentence adds value without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers key behaviors and parameters well, but omits what the response contains (e.g., returns created course object or ID). With no output schema, this information is important for the agent to process results.
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%, but the description adds meaning beyond schema by explaining the impact of courseType and accessMode, and clarifying purpose of siteId and confirmProductionWrite. This enriches understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'course or community', distinguishing between the two types. It effectively differentiates from sibling tools like thincms_update_course and thincms_delete_course.
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?
Includes explicit guidance on defaults (draft status), courseType behavior, and accessMode options. While it doesn't explicitly say when not to use this tool, the context of creation is clear and usage is well-explained.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enroll a learner in a course. The user must already exist — specify by email or userId. This bypasses payment requirements, effectively creating a free/invite enrollment.
| Name | Required | Description | Default |
|---|---|---|---|
| No | Learner's email address (looks up existing user) | ||
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| source | No | Enrollment source label (default: invite) | |
| status | No | Enrollment status (default: active) | |
| userId | No | User ID (alternative to email) | |
| courseId | Yes | Course ID (required) | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behavioral trait: bypasses payment requirements, creating free/invite enrollment. With no annotations, description covers this important aspect. Could mention output or side effects but sufficient.
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 with no wasted words. First sentence states purpose and prerequisite, second adds key behavioral note. Highly concise and front-loaded.
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 no output schema and moderate complexity, description covers purpose, prerequisites, and behavior. Lacks return value description but adequate for a create tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions. Description adds context (email/userId alternatives, defaults) but doesn't provide critical new meaning beyond schema. 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?
Clearly states the action 'Enroll a learner in a course', specifies the resource, and distinguishes from sibling tools like update/delete/list enrollments by emphasizing creation and bypassing payment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states prerequisites (user must exist, specify by email or userId) and implies this is for free/invite enrollments. No explicit when-not or alternatives, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new form or survey. Use renderMode 'fields' for standard forms (with field definitions) or 'html' for custom HTML surveys served at /s/:slug. Use preset 'contact' or 'newsletter' for pre-configured field sets. For large HTML content (>10KB), use htmlContentFile instead of htmlContent to pass a local file path.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Form name (required) | |
| slug | No | URL slug (auto-generated from name if omitted) | |
| fields | No | Field definitions (for renderMode 'fields') | |
| preset | No | Pre-configured field set | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| enabled | No | Enable/disable form (default: true) | |
| renderMode | No | 'fields' for standard forms, 'html' for custom survey HTML (default: fields) | |
| webhookUrl | No | URL to receive submission payloads via POST | |
| description | No | Form description | |
| htmlContent | No | Custom HTML content (for renderMode 'html', served at /s/:slug) | |
| successMessage | No | Message shown after successful submission | |
| webhookUrlTest | No | Test webhook URL (auto-deactivates after one delivery) | |
| htmlContentFile | No | Local file path containing HTML content — use this instead of htmlContent for large surveys (>10KB). The file is read and sent as htmlContent. | |
| webhookTestMode | No | Enable test mode for webhook | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that HTML surveys are served at /s/:slug and that htmlContentFile relates to file paths for large content. However, it doesn't mention side effects like enabling/disabling defaults or triggering webhooks, leaving some behavioral gaps.
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 three sentences, each providing distinct, necessary information. It is front-loaded with the core verb and resource, and every sentence provides actionable guidance without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description covers core functionality and key parameters. However, it does not mention what the tool returns upon creation (e.g., form ID or confirmation), which would be helpful for an agent using the result. It also omits important contextual details like the siteId parameter's role (though described in schema). Overally, quite complete for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so baseline is 3. The description adds value by explaining the purpose of renderMode, preset, and the trade-off between htmlContent and htmlContentFile. It also mentions auto-generation of slug, which goes beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new form or survey' and distinguishes between two render modes ('fields' for standard forms, 'html' for custom HTML surveys). It also mentions presets for pre-configured fields, making the purpose specific and distinct from sibling create tools.
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 provides explicit guidance on when to use each renderMode and preset, and advises using htmlContentFile for large HTML content instead of htmlContent. This effectively tells the agent when to use different options, though it doesn't compare to siblings but that's unnecessary as this is the only form creation tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Configure a new email platform integration (one per site). Platform: activecampaign, kit, mailchimp, gohighlevel.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | User-facing label (e.g. 'My ActiveCampaign') | |
| config | Yes | Platform-specific config. ActiveCampaign: { apiUrl, apiKey, listId, fromEmail?, fromName?, addressId? }. GoHighLevel: { apiKey (Private Integration Token), locationId, listId? (a Workflow ID enrolled on submission) } — note GoHighLevel has no lists and email campaigns are managed inside GoHighLevel, not via ThinCMS campaigns. | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| platform | Yes | Platform identifier (e.g. 'activecampaign') | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It mentions the 'one per site' constraint and config details, but does not disclose if the operation is idempotent, required permissions, or side effects of creating against an existing integration. Adequate but not thorough.
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 a single clear sentence followed by a platform list. No wasted words, front-loaded with the core action. Excellent conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (nested config, 5 params, no output schema), the description lacks return value info and does not reference related tools like thincms_get_integration for checking existing integrations. The config schema helps, but overall completeness is moderate.
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 descriptions for parameters (especially config) are extensive. The tool description adds minimal extra value beyond listing platforms and the constraint, so 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 clearly states the verb 'Configure' and resource 'new email platform integration', lists specific platforms, and notes the 'one per site' constraint. This effectively distinguishes it from siblings like thincms_update_integration.
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 when to use (first-time setup) via 'one per site', but does not explicitly mention alternatives like thincms_get_integration to check if one exists. Context is clear but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new lead magnet. A lead magnet is a downloadable resource offered in exchange for a form submission (e.g., newsletter signup).
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | URL slug (auto-generated from title if omitted) | |
| title | Yes | Lead magnet title (required) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| ctaText | No | CTA button text shown on the resources page (default: 'Get this resource'). Examples: 'Join the webinar', 'Take the survey', 'Download the guide'. | |
| enabled | No | Enable/disable lead magnet (default: true) | |
| mediaId | No | Media ID of the downloadable file | |
| formSlug | No | Form slug to associate with this lead magnet | |
| sortOrder | No | Sort order for listing | |
| landingUrl | No | Custom landing URL override. When set, resource cards link here instead of /resources/:slug. Use for standalone pages (e.g., '/webinar'). | |
| description | No | Description of the lead magnet | |
| thumbnailUrl | No | Thumbnail image URL | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits beyond creation. It lacks information on side effects, permissions, idempotency, or error handling, leaving a gap for a mutation operation.
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 two sentences, front-loaded with the action and a helpful definition. It is efficient but could be slightly more concise by omitting the definition if considered extraneous.
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 12 parameters and no output schema, the description is minimal. It does not cover return values, error conditions, or workflow context, leaving the agent underinformed for effective 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 description coverage is 100%, so the schema already documents all 12 parameters fully. The description adds no additional parameter-level meaning beyond 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?
Description clearly states the action ('create') and resource ('lead magnet'), with a concise definition of what a lead magnet is. The verb 'create' implicitly distinguishes it from sibling tools like update, delete, or list.
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 for creation, but provides no explicit guidance on when to use this vs. alternatives (e.g., update vs. create). No prerequisites or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new lesson within a module. Content is raw HTML. Lessons are auto-ordered within their module. For large content (>10KB), use contentFile instead of content.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | URL slug (auto-generated from title if omitted) | |
| title | Yes | Lesson title (required) | |
| isFree | No | Make this a free preview lesson (default: false) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| content | No | HTML content of the lesson | |
| dripDate | No | ISO date when this lesson becomes available (for scheduled drip mode) | |
| duration | No | Recording duration in seconds (e.g., 2700 for 45 minutes) | |
| moduleId | Yes | Module ID (required) | |
| videoUrl | No | Video embed URL (YouTube, Vimeo, etc.) | |
| isUnlocked | No | Manually unlock this lesson regardless of drip settings | |
| contentFile | No | Local file path containing HTML content — use instead of content for large lessons | |
| recordingDate | No | ISO date when the live session was held (for community recordings, distinct from createdAt) | |
| videoDuration | No | Video duration (e.g., '10:30') | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. It discloses auto-ordering and large content handling, but does not mention side effects, failure modes, or dependencies like site configuration. Adds some behavioral context but not comprehensive.
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 with no wasted words. Each sentence adds meaningful information: core purpose, content format, auto-ordering, and size guidance. Excellent front-loading.
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 14 parameters and no output schema, the description is adequate but minimal. It covers the main use case but lacks details on return value, error scenarios, or side effects. Could be more complete for a complex creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions. The tool description adds value beyond schema by explaining when to use contentFile over content (size threshold). This extra guidance improves parameter selection.
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 'Create a new lesson within a module', specifying verb ('Create'), resource ('lesson'), and context ('within a module'). It also mentions content is raw HTML and lessons are auto-ordered, distinguishing it from sibling update/delete tools.
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 explicit guidance: for large content (>10KB) use contentFile instead of content. This helps the agent choose the right parameter. However, it does not explicitly state when to use this tool versus alternatives like update_lesson, but the creation context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new module within a course. Modules are auto-ordered by creation sequence.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Module title (required) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| courseId | Yes | Course ID (required) | |
| description | No | Module description | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must bear full burden. It mentions auto-ordering but does not disclose that this is a write operation requiring production confirmation, potential side effects, or prerequisites like the course must exist.
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 two sentences, front-loading the primary action and key behavior. Every word is essential with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, no output schema, and no annotations, the description is minimal. It lacks details on return values, error handling, and prerequisites, leaving some gaps for proper 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 100%, so parameters are well-documented. The description adds no extra meaning beyond the schema's parameter descriptions, which is acceptable per baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create', the resource 'module', and the scope 'within a course'. It distinguishes from siblings like thincms_create_course or thincms_update_module. The auto-ordering note adds specificity.
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 when to use it (to create a module in a course) but does not provide explicit guidance on when not to use it or mention alternative tools like thincms_reorder_modules for reordering.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new static page. Content should be raw HTML. Use renderMode 'wrapped' for pages that use the site template, or 'standalone' for full custom HTML. For large content (>10KB), use contentFile instead of content to pass a local file path.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | URL slug (auto-generated from title if omitted) | |
| title | Yes | Page title (required) | |
| jsonLd | No | Custom JSON-LD (Schema.org) injected verbatim into the page <head>. Pass valid JSON as a string. Use for Service, Event, BreadcrumbList, HowTo, Article, etc. Set to empty string to clear. | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| status | No | Page status (default: draft) | |
| content | No | HTML content | |
| noIndex | No | Set true to add noindex meta tag | |
| metaTitle | No | SEO meta title | |
| ogImageUrl | No | Open Graph image URL | |
| renderMode | No | Render mode (default: wrapped) | |
| contentFile | No | Local file path containing HTML content — use this instead of content for large pages (>10KB). The file is read and sent as content. | |
| canonicalUrl | No | Canonical URL | |
| metaDescription | No | SEO meta description | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must stand alone. It discloses the content format requirement and content size limit, but does not mention default behaviors (e.g., slug auto-generation, status default), return values, or potential side effects. This is adequate but not thorough.
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 three sentences, each serving a purpose: first states what the tool does, second clarifies renderMode, third addresses large content. No extraneous information, and the most important details come first.
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 has 14 parameters and no output schema, the description covers the most critical usage context (content format, renderMode, contentFile). However, it lacks information about return values, error conditions, or additional behavioral details. It is adequate for basic usage but leaves gaps.
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 baseline is 3. The description adds value by explaining the purpose of renderMode options and when to use contentFile instead of content, which goes beyond the schema descriptions. This provides meaningful guidance for these parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new static page', specifying the action and resource. It distinguishes from siblings by explicitly mentioning 'static page', differentiating it from posts, courses, etc. The mention of raw HTML and render modes adds specificity.
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 provides explicit guidance on when to use each renderMode ('wrapped' vs 'standalone') and when to use contentFile over content (>10KB). It does not explicitly state when not to use this tool vs alternatives, but the context is clear enough for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new popup/CTA. Each popup is linked to an existing form (by formId) which handles the actual data collection. The popup provides the presentation container, trigger logic, and targeting rules. Display types: 'overlay' (centered modal), 'sticky-top'/'sticky-bottom' (fixed bars), 'slide-in' (bottom-right card). On mobile, overlay auto-downgrades to sticky-bottom to avoid Google's interstitial penalty.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Popup name (required) | |
| slug | No | URL slug (auto-generated from name if omitted) | |
| formId | Yes | ID of the form to display inside the popup (required) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| enabled | No | Enable/disable popup (default: true) | |
| bodyText | No | Body text shown between headline and form | |
| headline | No | Headline text shown above the form | |
| priority | No | Priority (higher = more important). Specific-scope always beats site-wide regardless of priority. Default: 0 | |
| customCss | No | Custom CSS to override default popup styles | |
| targeting | No | Page targeting rules (default: site-wide) | |
| displayType | No | Display type (default: overlay) | |
| suppressDays | No | Days to suppress after visitor dismisses (default: 30) | |
| ctaButtonText | No | CTA button text shown in step 1 of the two-step popup flow (default: 'Sign up'). Examples: 'Sign up', 'Book now', 'Get started', 'Download' | |
| mobileEnabled | No | Show on mobile devices (default: true) | |
| triggerConfig | No | Trigger configuration (default: time-delay 8s) | |
| mobileDisplayType | No | Override display type on mobile (default: auto-downgrade overlay to sticky-bottom) | |
| suppressOnConvert | No | Days to suppress after visitor submits the form (default: 180) | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description takes full responsibility. It discloses key behaviors: popups require an existing form, display types and mobile auto-downgrade, trigger configuration, and the confirmProductionWrite safety parameter. It does not mention auth needs or rate limits but covers substantial behavioral 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 a single paragraph with clear, informative sentences. It covers essential points without redundancy. While it could be slightly more concise (e.g., using bullet points), it is well-structured and front-loaded with the core purpose.
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 an 18-parameter creation tool with no output schema, the description provides substantial context: linking to forms, display types, mobile behavior, triggers, and safety. However, it lacks information about the return value (e.g., created popup object), which would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents each parameter in detail. The description adds minimal extra semantic value beyond reiterating display types and mobile behavior. It integrates parameters into a narrative but does not significantly surpass the schema's explanations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new popup/CTA' and explains its role as a presentation container linked to a form. It distinguishes from sibling tools like update_popup and delete_popup by focusing on creation. The specific verb and resource make the purpose 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 when to use this tool (e.g., needing a popup with a form, display types, triggers) but does not explicitly compare with alternatives like lead magnets or other content creation tools. It lacks exclusion guidance or clear context for when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a blog post. Content should be raw HTML. Tags are auto-created if they don't exist. For large content (>10KB), use contentFile instead of content. Posts with status="published" and a publishedAt in the past appear on the public site immediately; a future publishedAt is auto-scheduling — they appear when the timestamp passes (no worker required, the public site filters by date). Posts with status="draft" never appear publicly regardless of dates. Use scheduledFor="immediate" to publish now, or scheduledFor=<ISO timestamp at least 60 min in the future> to schedule.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | URL slug (auto-generated from title if omitted) | |
| tags | No | Array of tag names (auto-created if new) | |
| title | Yes | Post title (required) | |
| jsonLd | No | Custom JSON-LD (Schema.org) injected verbatim into the post <head>. Pass valid JSON as a string. Use for HowTo, Recipe, Event, etc. (Article + BreadcrumbList are auto-emitted.) Set to empty string to clear. | |
| series | No | Series name for multi-part content | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| status | No | Post status (default: draft) | |
| content | No | HTML content of the post | |
| excerpt | No | Short summary/excerpt | |
| noIndex | No | Exclude this post from search engine indexing (default: false) | |
| authorId | No | Author ID | |
| featured | No | Mark as featured post | |
| metaTitle | No | SEO meta title | |
| ogImageUrl | No | Open Graph image URL | |
| categoryIds | No | Array of category IDs | |
| contentFile | No | Local file path containing HTML content — use this instead of content for large posts (>10KB). The file is read and sent as content. | |
| gatePreview | No | Custom HTML teaser shown before the gate. If omitted, the excerpt or first 2 paragraphs are used. | |
| pinnedUntil | No | ISO date: pin post until this date | |
| publishedAt | No | DEPRECATED — use scheduledFor. ISO date for publication date. | |
| scheduledAt | No | DEPRECATED — use scheduledFor. Legacy field, no longer affects visibility. | |
| seriesOrder | No | Order within series | |
| canonicalUrl | No | Canonical URL | |
| scheduledFor | No | When the post should become public. Pass "immediate" to publish now, or an ISO 8601 timestamp at least 60 minutes in the future to schedule. Required at status="published" — Phase 3 will reject omission. Posts with status="draft" ignore this field. | |
| gatedFormSlug | No | Form slug to gate this post behind. Visitors must submit the form to see full content. Set to empty string to remove gating. | |
| membersContent | No | HTML content visible only to authenticated members/subscribers. Shown after the main content for logged-in members. | |
| metaDescription | No | SEO meta description | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully bears the burden of behavioral disclosure. It explains the effects of different statuses, the scheduling mechanism, auto-creation of tags, validations like 60-minute minimum for scheduledFor, and mentions deprecated fields. This is comprehensive and transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, starting with the core action and then providing specifics. Each sentence adds useful information without redundancy. It could be slightly more structured (e.g., bullet points), but it is efficient and front-loaded with the most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (27 parameters, no output schema), the description covers input-related behavior thoroughly, including guidance on large content, scheduling, status effects, production write confirmation. However, it does not describe the return value or response structure, which would help an agent understand what to expect after creation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the baseline is 3. The tool description adds significant value by explaining the interplay between status, publishedAt, savedAt, and scheduledFor, and why contentFile exists for large content. This goes beyond what the schema descriptions provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a blog post' and specifies that content should be raw HTML. It distinguishes this tool from siblings like thincms_update_post and thincms_bulk_create_posts by focusing on single post creation. The behavior around status and scheduling is precisely explained.
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 provides clear context for when to use this tool (creating a single post) and includes guidance on choosing between 'content' and 'contentFile' based on size, as well as how to schedule posts. However, it does not explicitly mention alternatives or when not to use this tool, such as for updates or bulk creation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a preview session with draft template or content overrides. Returns a token-based preview URL (valid for 2 hours). Use this to preview CSS/template changes or draft content without publishing.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| pageFrame | No | Draft HTML page frame to preview | |
| stylesheet | No | Draft CSS to preview | |
| customHeadHtml | No | Draft custom head HTML to preview | |
| contentOverrides | No | Array of post/page content overrides to preview | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden of behavioral disclosure. It mentions the preview URL is token-based and valid for 2 hours, and implies the operation is non-destructive ('without publishing'). However, it does not disclose whether creating a preview modifies state, idempotency, or any side effects.
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 consists of two sentences that are front-loaded with the primary action. There is no fluff or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 optional parameters and no output schema, the description provides adequate context: what the tool does, key features (token-based, 2-hour validity), and use case. It could be more complete by mentioning the response format or prerequisites, but it is sufficient overall.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter description coverage, so the schema already documents each parameter fully. The description adds no additional meaning beyond what is in the schema, so a baseline score of 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 clearly states it creates a preview session with draft template or content overrides and returns a token-based URL. It distinguishes from sibling tools like thincms_get_preview_url (which likely retrieves an existing preview) and thincms_go_live (which publishes).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this to preview CSS/template changes or draft content without publishing,' which gives clear context for when to use the tool. It does not explicitly state when not to use or mention alternatives, but the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new quiz within a module. Quizzes share sort order with lessons — use thincms_reorder_module_items to position them. Two feedback modes: 'show_answer' reveals correct answers after submission, 'retry' shows only the score.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | URL slug (auto-generated from title if omitted) | |
| title | Yes | Quiz title (required) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| moduleId | Yes | Module ID (required) | |
| feedbackMode | No | Feedback mode (default: show_answer) | |
| passingScore | No | Passing score percentage (default: 70) | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It mentions creation, sorting behavior, and feedback modes, but does not cover potential side effects (e.g., whether existing quizzes are affected) or required permissions. It provides reasonable but not exhaustive transparency.
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 two sentences, front-loads the core action, and includes only essential information (sort order, feedback modes). No redundancy or extraneous details.
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 7 parameters, no output schema, and no annotations, the description covers creation context, sorting integration, and feedback modes. It could mention the module relation more explicitly, but overall it provides sufficient context for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema; it mentions feedback modes but does not elaborate on parameter constraints or relationships. The schema already describes parameters adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new quiz within a module' and distinguishes from sibling tools like thincms_create_lesson by noting that quizzes share sort order with lessons and by specifying unique feedback modes.
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 provides explicit guidance on sorting ('use thincms_reorder_module_items to position them') and explains the two feedback modes, helping the agent decide when to use this tool. It lacks explicit when-not-to-use or alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a URL redirect. Source path must start with /. Use /* suffix for wildcard matching.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | Admin note explaining this redirect | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| enabled | No | Enable/disable the redirect (default: true) | |
| targetUrl | Yes | Target URL — relative path or absolute URL (required) | |
| sourcePath | Yes | Source path, e.g. '/old-page' or '/blog/*' (required) | |
| statusCode | No | 301 (permanent) or 302 (temporary). Default: 301 | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It only states that the tool creates a redirect, without mentioning side effects, authorization requirements, rate limits, or what happens on duplicate source paths. For a write operation, this is insufficient.
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 extremely concise: two sentences with no redundancy. Every word adds value. It is front-loaded with the core purpose and immediately follows with key constraints.
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 no output schema, the description does not explain the return value or error scenarios. However, the input schema is well-documented, and the tool is a straightforward creation operation. The description is adequate for basic use but lacks completeness for edge cases or output expectations.
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?
All 7 parameters have descriptive schema entries (100% coverage), so the description adds little beyond restating the source path rule. The description reinforces the wildcard usage but does not add new semantic value for other parameters. 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 clearly states 'Create a URL redirect' with a specific verb and resource. It also provides additional constraints (source path must start with /, wildcard matching with /*). This distinguishes it clearly from sibling tools like update, delete, list, get, and import.
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 gives some usage guidance (path prefix and wildcard syntax) but does not explicitly state when to use this tool versus alternatives like thincms_update_redirect or thincms_import_redirects. The guidance is implied by the tool name but not elaborated, limiting its helpfulness for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a script injection for the public site. Scripts can be placed in the or before .
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | Script code including <script> tags (required) | |
| name | Yes | Script name, e.g. 'Google Analytics' (required) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| enabled | No | Enable/disable the script (default: true) | |
| placement | No | Where to inject: 'head' or 'body' (default: head) | |
| sortOrder | No | Sort order for execution priority | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must convey behavioral traits. It lacks details on side effects, prerequisites, or impact (e.g., immediate live effect, permission needs).
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 concise sentences, no unnecessary words, direct and front-loaded.
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 7 parameters, no output schema, and no annotations, the description is too brief. It omits return value, constraints, and effects on existing scripts.
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 description adds minimal extra meaning beyond the schema's parameter descriptions. 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?
Clearly states it creates a script injection for the public site, with placement details. Distinguishes from siblings like thincms_list_scripts and thincms_update_script.
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?
Implies usage for adding scripts but provides no when-to-use or when-not-to-use guidance, nor comparison with alternative tools like thincms_append_css.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new environment variable secret. The value is stored securely and never returned in API responses.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Variable name, e.g. 'STRIPE_KEY' (required) | |
| value | Yes | Secret value (required) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| description | No | Description of what this secret is for | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description bears full burden. It only states the secret is stored securely and never returned, but omits critical behavioral traits like mutation side effects, idempotency on duplicate key, or that it's a write operation requiring permissions. Incomplete for a create 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?
Two concise sentences, front-loaded with the action. No wasted words. Every sentence adds value.
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 5 parameters (2 required) and no output schema, the description covers the core purpose but lacks context on idempotency, duplicate keys, site scoping, and write permissions. The detailed schema partially compensates, but overall completeness is minimal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions (e.g., siteId explains overriding active site). The tool description adds no extra meaning beyond the schema, so 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 'Create a new environment variable secret. The value is stored securely and never returned in API responses.' clearly states the verb (create), resource (environment variable secret), and a key behavioral feature (secure, never returned). It distinguishes from sibling tools like thincms_list_secrets.
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?
No guidance on when to use vs alternatives (e.g., thincms_list_secrets). Lacks context about prerequisites, site scoping, or avoiding duplicate keys. Does not mention when-not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new email sequence.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Sequence name | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| triggerFormSlug | No | Form slug that triggers enrollment | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It only states the tool creates a sequence, but does not mention that it is a write operation, any side effects, or what happens upon success. The parameters like 'confirmProductionWrite' hint at production safeguards, but the description itself adds no behavioral 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 concise (one sentence), but it is overly minimal for a tool with 4 parameters and no output schema. It lacks structure and could benefit from additional essential information without being verbose.
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 complexity (4 params, no output schema, many siblings), the description is incomplete. It does not explain what an email sequence is, its relationship to other entities, or what the return value is. This is a significant gap for a creation 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 100%, so each parameter is already documented. The description does not add any extra meaning or context beyond what the schema provides. Baseline score of 3 is appropriate as the description adds no value over 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?
The description clearly states the action 'Create' and the resource 'email sequence', which is specific and not a tautology. However, it does not differentiate this tool from other creation tools among siblings, nor does it provide any contextual information about what an email sequence is.
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 offers no guidance on when to use this tool versus alternatives. It does not mention prerequisites, when creation is appropriate, or when to use other sequence tools (e.g., update, delete). This leaves the agent without decision-making context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new tag. Note: tags are also auto-created when included in the tags array of a post.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Tag name (required) | |
| slug | No | URL slug (auto-generated from name if omitted) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| description | No | Tag description (displayed on tag archive page, used in meta description) | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses that tags can be auto-created via posts, which is a useful behavioral insight. However, it doesn't address what happens on duplicate names, idempotency, 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?
The description is very short and front-loaded with the core action. The note is placed after, maintaining conciseness. It could be slightly more structured but effectively communicates the essential point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and rich schema documentation, the description provides adequate context for a create operation. However, it lacks information about return values (e.g., created tag object) and potential errors, which would help completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers all parameters with descriptions, so baseline is 3. The description adds no extra parameter-level meaning beyond the note about auto-creation, which is not parameter-specific.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new tag with a specific verb and resource. The note about auto-creation via posts adds nuance, but it doesn't explicitly differentiate from other tag operations like update or list.
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?
No guidance on when to use this tool versus alternatives (e.g., thincms_update_tag, thincms_delete_tag). The note about auto-creation hints at a scenario but doesn't provide explicit usage boundaries or decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new Tool. html is the raw HTML/JS payload that renders inside a sandboxed iframe with a window.thinCMS runtime injected. Set authRequired to 'password' | 'google' | 'either' to gate access; 'none' makes the tool public. Set systemPrompt to prepend a persona to /ai/chat calls. For large HTML payloads (>10KB), use htmlFile with a local file path.
| Name | Required | Description | Default |
|---|---|---|---|
| html | No | Raw HTML/JS payload | |
| name | Yes | Tool name (required) | |
| slug | No | URL slug (auto-generated from name if omitted) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| status | No | Publish status (default: draft) | |
| aiModel | No | Override site AI model for this tool (e.g. claude-sonnet-4-6) | |
| enabled | No | Enabled (default: true) | |
| htmlFile | No | Local file path containing the HTML payload — use instead of html for large tools | |
| rateLimit | No | AI chat calls per end-user per hour (omit or null for unlimited) | |
| allowSignup | No | Whether the login screen offers self-signup (default: true) | |
| description | No | Short description shown in admin UI | |
| authRequired | No | Auth mode (default: none) | |
| systemPrompt | No | Default system prompt prepended to ai/chat calls | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It discloses the sandboxed iframe behavior, auth gating, and systemPrompt usage. However, it omits side effects, permissions required, or whether the tool is immediately active. The description is adequate but not exhaustive.
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 sentences with key information front-loaded. Every sentence adds value. Could be slightly more structured (e.g., bullet points) but remains clear and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the main behavioral aspects and key parameters, but missing return value description (no output schema) and does not mention sensitive parameters like `confirmProductionWrite`. For a 14-parameter tool, some details are omitted.
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 covers all parameters with descriptions. The description adds value by explaining the `html` parameter's rendering context, the meaning of `authRequired` values, and the purpose of `systemPrompt`. It also clarifies when to use `htmlFile`. This compensates for the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Create a new Tool' and explains the tool as an HTML/JS payload rendered in a sandboxed iframe. It clearly distinguishes the create operation from other tool actions by specifying the verb and resource.
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 explicit guidance on when to use `htmlFile` instead of `html` for large payloads and describes the auth options. Lacks explicit when-not-to-use or alternatives among siblings, but since it's the only create tool, the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a workbook inside a module. Workbooks are fillable forms that live alongside lessons and quizzes — use thincms_reorder_module_items to position them. The fields array defines the form spec. For large specs (>10KB), use fieldsFile instead.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | URL slug (auto-generated from title if omitted) | |
| title | Yes | Workbook title (required) | |
| fields | No | Ordered array of field definitions. Each field is an object with at minimum { fieldId, type, label }. v1 field types: short_text, long_text, number, rating, select, multi_select, date, prompt_display, markdown_display. Input fields may include `prefillFrom: { courseSlug, workbookSlug, fieldId }` for cross-workbook references. | |
| isFree | No | Make this workbook a free preview (default: false) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| dripDate | No | ISO date when this workbook becomes available (scheduled drip mode) | |
| moduleId | Yes | Module ID (required) | |
| fieldsFile | No | Local file path containing a JSON array of field definitions — use for large workbook specs | |
| isUnlocked | No | Manually unlock regardless of drip settings | |
| description | No | HTML content shown above the form | |
| introContent | No | Optional additional HTML intro shown after the description | |
| requiredForCompletion | No | Whether marking the workbook complete is required for module completion (default: true) | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. | |
| allowExportBeforeComplete | No | Whether learners can export before marking complete (default: true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It does not mention that the tool performs a write operation, any required permissions, side effects on module item order, or the nature of the response (e.g., returns created workbook). This lack of transparency leaves the agent underinformed.
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 extremely concise, consisting of two short sentences. Each sentence earns its place: the first states the core purpose and context, the second offers an important alternative for large specs. No wasted words.
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 (14 parameters, no output schema), the description is minimal. It does not discuss return values, error conditions, prerequisites (e.g., module existence), or the confirmProductionWrite safety parameter. While the schema descriptions fill some gaps, the description could do more to ensure the agent fully understands the tool's usage context.
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 schema descriptions cover all 14 parameters (100% coverage), so the description does not need to repeat them. The description adds useful context by explaining the fields array as defining the form spec and introducing fieldsFile as an alternative for large specs, which goes beyond the schema's individual field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a workbook inside a module') and differentiates the tool from siblings by specifying that workbooks are fillable forms living alongside lessons and quizzes, and by referencing the reorder tool for positioning. It also introduces key concepts like fields and fieldsFile.
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 provides guidance on post-creation positioning via thincms_reorder_module_items and on choosing between fields and fieldsFile for large specs. However, it does not explicitly state prerequisites (e.g., module must exist) or when to avoid this tool in favor of alternatives like thincms_create_form.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an author by ID. Posts by this author will have their author unset.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Author ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that posts lose their author, which is a useful behavioral trait. However, it lacks details on irreversibility, permission requirements, or other side effects. With no annotations, the description carries full burden and is insufficient.
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, efficient and front-loaded with the verb 'Delete'. Every word earns its place; no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is incomplete given the lack of output schema and annotations. It does not specify the return value (e.g., success message, deleted object) or provide usage context among many sibling 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 coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema's parameter descriptions (e.g., no explanation of id, siteId, confirmProductionWrite).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete an author by ID) and a key side effect (posts have author unset). This distinguishes it from other author tools (create/update) but doesn't specify when to use this versus other deletion tools (e.g., delete_post).
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?
No usage guidelines are provided. The description does not indicate when to use this tool, when not, or suggest alternatives. For a deletion operation, prerequisites or warnings about cascading effects are missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a campaign.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Campaign ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully bears the burden of behavioral disclosure. 'Delete a campaign' implies an irreversible destructive action, but the description does not mention cascading effects, confirmation requirements (confirmProductionWrite from schema), or whether the action can be undone. This is insufficient for a deletion 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?
The description is a single sentence, concise but too minimal. It avoids verbosity but sacrifices completeness. Every word earns its place, but the description could be more informative without bloating (e.g., adding a sentence about confirmProductionWrite or irreversibility).
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 (3 params, no output schema), the description is incomplete. It fails to mention that the action is destructive, that confirmProductionWrite may be required, or that it permanently removes a campaign. The schema covers parameter details, but the description leaves critical context unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond what the schema already provides for parameters like id, siteId, and confirmProductionWrite. No extra value, but no harm.
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 'Delete a campaign.' clearly states the action and resource. It is straightforward but does not differentiate from other delete tools in the sibling list, which all follow a similar pattern. A higher score would require explicit distinction, 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?
No guidance on when to use this tool versus alternatives (e.g., unpublish, archive). There is no mention of prerequisites, required permissions, or scenarios where deletion is appropriate vs. other actions. The description provides no context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a category by ID. Posts in this category will be uncategorized.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Category ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose all behavioral traits. It mentions the side effect of uncategorized posts, but it does not address reversibility, permission requirements, rate limits, or confirmation steps. This is insufficient for a destructive operation.
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 two sentences with no unnecessary words. It is efficiently front-loaded with the core action and immediate consequence.
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 tool is a simple delete with no output schema. The description covers the primary side effect but omits return value, error cases, or success indication. Adequate for a straightforward operation but could be more informative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description does not add any detail beyond what the schema already provides. The description does not elaborate on parameters, so it meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and resource ('category by ID'). It also mentions the side effect that posts become uncategorized, which distinguishes it from other delete tools in the sibling list.
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 when to use it (to delete a category) but does not provide explicit guidance on when not to use it or alternatives (e.g., updating the category to clear posts). No direct comparison with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a collection and all its items. Any {{collection:slug}} references will render as empty.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Collection ID to delete | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It covers the cascade delete and reference impact, but lacks details on irreversibility, permission requirements, or error handling.
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 extremely concise: two sentences that front-load the action and immediately follow with a key consequence. No wasted words.
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 destructive tool with no output schema, the description adequately explains the cascade and reference effect. It could mention irreversibility or recovery options, but it is sufficiently complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameter descriptions, so the tool description adds no extra meaning. Baseline score of 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 clearly states the verb 'Delete' and the resource 'a collection and all its items', distinguishing it from sibling delete tools for other resources. It also notes the side effect on references, adding specificity.
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 for permanently removing a collection, and warns about references rendering empty. However, it does not explicitly mention when to use alternatives (e.g., update instead of delete) or when not to use (e.g., if references are critical).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an item from a collection.
| Name | Required | Description | Default |
|---|---|---|---|
| itemId | Yes | Item ID to delete | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| collectionId | Yes | Collection ID | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits like irreversibility, cascade effects, or the need for the confirmProductionWrite parameter. For a destructive operation, more transparency is needed.
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?
Single sentence, concise and front-loaded with the action. However, it omits useful context that could be added in a few more words.
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?
No output schema, and the description does not explain return values or post-deletion state. While parameters are well-documented in schema, the description lacks completeness for a deletion tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The tool description adds no additional parameter meaning, so baseline score of 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 'Delete an item from a collection' clearly states the verb (delete) and resource (item from collection), distinguishing it from sibling tools like thincms_delete_collection and other item delete functions.
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?
No guidance on when to use this tool versus alternatives (e.g., thincms_delete_collection for the entire collection, or thincms_update_collection_item for modifications). Missing prerequisites or context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a content block. Any {{block:slug}} references in templates or content will render as empty.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Content block ID to delete | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries full burden. It discloses the destructive nature (deletion) and the side effect of broken template references, which is valuable. However, it does not mention permissions, reversibility, or the confirmProductionWrite parameter's role in production safety.
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, no redundant text, and the most important info (delete + side effect) is front-loaded. Every sentence 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 delete operation with three well-documented parameters and no output schema, the description covers the essential side effect. It lacks mention of return behavior or confirmProductionWrite, but overall is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameters documented in the input schema. The description adds no extra parameter context beyond what the schema already provides, so a baseline of 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 clearly states the action 'Delete a content block' and specifies the resource type. It distinguishes from siblings like thincms_delete_post or thincms_delete_course by focusing on content blocks. The additional note about template references adds clarity.
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?
No guidance on when to use this tool versus alternatives such as thincms_update_content_block or thincms_delete_post. No when-not-to-use or prerequisite conditions are mentioned, leaving the agent to infer based on name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a course and all its modules, lessons, quizzes, and enrollments.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Course ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description explicitly states the cascading deletion behavior (all modules, lessons, quizzes, enrollments), which is critical behavioral context. It does not disclose reversibility or permission requirements, but the destructive scope is clearly communicated.
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 a single, efficient sentence with no wasted words. It front-loads the key action and scope, making it easy to parse.
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 delete tool, the description covers the essential behavior (cascade). It could mention irreversibility or production write confirmation (handled by schema), but overall it is sufficiently complete given the tool's simplicity and the absence of an output schema.
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 each parameter already has a description. The tool description adds no additional semantic value beyond what the schema provides. 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 uses a specific verb ('Delete') and resource ('course'), and clearly distinguishes from sibling tools like thincms_delete_lesson by listing the cascade of deletions (modules, lessons, quizzes, enrollments). This makes the tool's purpose 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 provides no guidance on when to use this tool versus alternatives like thincms_delete_module for partial deletions, nor does it mention when not to use it. No usage context or exclusion criteria are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an enrollment permanently.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Enrollment ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose all behavioral traits. It only states 'permanently', but fails to mention permissions requirements, cascading effects on related data, or whether the operation can be undone.
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 a single sentence with no wasted words. It is appropriately concise, though it could benefit from additional context without becoming verbose.
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 lack of annotations and output schema, the description is minimally adequate. It covers the core action but omits important context about permanence, required permissions, and potential consequences.
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 tool description does not add any further meaning beyond the schema's parameter descriptions, which are already detailed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (delete) and resource (enrollment), and the word 'permanently' adds finality. However, it does not differentiate from other delete tools or specify the required identifier, but it is not a tautology.
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?
No guidance is provided on when to use this tool versus alternatives like update or list enrollment. There is no mention of prerequisites, such as needing the enrollment ID from a list, or warnings about irreversibility.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a lead magnet by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Lead magnet ID to delete | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden of disclosing behavioral traits such as irreversibility, cascading effects, or permissions. It merely states the action without any such transparency.
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 a single clear sentence with no extraneous words, achieving high conciseness. However, it may be slightly too brief, lacking behavioral context, which prevents a perfect score.
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 absence of an output schema and the presence of optional parameters (siteId, confirmProductionWrite), the description lacks completeness. It does not explain return values, side effects, or the meaning of the optional parameters in context.
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 all parameters are already documented in the schema. The description adds no extra meaning beyond what the schema provides, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the resource ('lead magnet') with a specific identifier ('by ID'). It is unambiguous and distinguishes itself from sibling tools like thincms_create_lead_magnet or thincms_update_lead_magnet.
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?
No usage guidelines are provided. The description does not mention when to use this tool versus alternatives, nor does it offer any prerequisites or exclusions. An agent must infer context from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a lesson and its attachments.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Lesson ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the core behavior (deletes lesson and attachments) but is minimal. No annotations provided, so the description carries full burden. It does not mention whether deletion is reversible, any side effects, or auth requirements. Adequate for a straightforward delete.
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?
One short sentence delivers the core purpose. No unnecessary words or repetition. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description is minimal but covers the essential purpose. Could benefit from details on deletion behavior (e.g., permanence, required permissions) but is not incomplete. Adequate for a simple delete operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds no parameter-specific meaning beyond what the schema already provides. The schema sufficiently documents each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete'), the resource ('a lesson'), and includes scope ('and its attachments'). It is specific and distinct from sibling tools like thincms_delete_course, thincms_delete_module, etc. No ambiguity.
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?
No guidance on when to use this tool versus alternatives (e.g., thincms_update_lesson for edits, or other delete tools). No mention of prerequisites or when not to use. Minimal context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a file attachment from a lesson.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| lessonId | Yes | Lesson ID (required) | |
| attachmentId | Yes | Attachment ID (required) | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states 'Delete' without disclosing destructive behavior, permanence, permissions, or side effects (e.g., confirming production write through confirmProductionWrite parameter description, but not in the main description).
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 a single concise sentence (8 words), front-loading the action. It is efficient with no wasted words, though slightly more context might be beneficial for a delete tool.
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 has 4 parameters and no output schema, the description lacks completeness. It does not mention irreversibility, prerequisites (e.g., need lessonId and attachmentId), or what happens after deletion. This could lead to misuse.
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 no extra meaning beyond the schema descriptions, which are already detailed for siteId and confirmProductionWrite. Thus, score is adequate but not improved.
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 'Delete a file attachment from a lesson' uses a specific verb (Delete) and resource (file attachment), clearly distinguishing it from sibling tools like thincms_upload_lesson_attachment and thincms_get_lesson_attachment_url.
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 gives no explicit guidance on when or when not to use this tool versus alternatives. For a straightforward delete operation, this is minimally adequate, but lacks context such as needing the attachment ID or being irreversible.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a media item and remove the file from disk.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Media ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full responsibility for behavioral disclosure. While it hints at destructiveness ('remove file from disk'), it does not mention reversibility, permission requirements, cascading effects on references, or any side effects beyond file deletion.
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 a single, efficient sentence with no extraneous words. It is front-loaded with the core purpose. However, it could benefit from minor expansion for clarity without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should clarify return values (e.g., success indicator). It mentions file removal but omits confirmation or error behavior. For a deletion operation on a content system, additional detail about scope (e.g., 'permanently delete') would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and parameter descriptions in the schema are already detailed (e.g., siteId, confirmProductionWrite). The tool description adds no additional semantic meaning beyond what the schema provides, so a baseline score of 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 clearly states the action ('Delete a media item') and specifies the additional effect ('remove the file from disk'). It is a specific verb+resource combination that distinguishes from sibling tools like upload, update, or get media.
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?
No guidance is provided on when to use this tool versus alternatives (e.g., thincms_update_media or thincms_get_media). There are no prerequisites, warnings about irreversible deletion, or conditional contexts such as needing a site ID.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a module and all its lessons and quizzes.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| courseId | Yes | Course ID (required) | |
| moduleId | Yes | Module ID (required) | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose all relevant behaviors. It explicitly states the cascading deletion of lessons and quizzes, which is good. However, it omits details about permissions, reversibility, or the need for confirmProductionWrite on production sites.
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 a single, efficient sentence with no wasted words. It could be slightly expanded with usage context, but it remains concise and front-loaded with the core purpose.
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 no output schema and a destructive operation, the description is minimally complete. It covers what is deleted but not the response format, error conditions, or safety measures like confirmProductionWrite. For a delete tool, more context about irreversibility and acknowledgments would be beneficial.
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 parameters are fully described in the schema. The description adds no additional meaning beyond the schema, meeting the baseline. It does not explain how to obtain courseId or moduleId, but that is acceptable given the schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('delete'), the resource ('module'), and the scope ('and all its lessons and quizzes'). It effectively distinguishes from sibling tools like thincms_delete_lesson or thincms_delete_quiz because it deletes an entire module with its child entities.
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?
No guidance on when to use this tool versus alternatives. For example, it does not mention that individual lessons or quizzes can be deleted separately using thincms_delete_lesson or thincms_delete_quiz, or that this operation is irreversible.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a static page by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Page ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Despite saying 'permanently delete', the description does not disclose consequential details like permissions required, cascading deletes, or whether operation is reversible. Partial transparency.
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?
Single sentence, direct and front-loaded. Could be slightly more informative without losing conciseness, but efficient overall.
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 delete action with no output schema, the description covers core purpose but lacks details like return value, error behavior, or idempotency. Adequate but not thorough.
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 schema descriptions are detailed (especially for siteId and confirmProductionWrite). The tool description adds no additional parameter context beyond the schema, so baseline of 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?
Description clearly states 'permanently delete a static page by ID', specifying action, resource, and identifier. Distinguished from sibling delete tools for other resources.
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?
No guidance on when to use or avoid this tool. No mention of prerequisites, alternatives, or side effects. The description is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a popup by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Popup ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior, but it only says 'delete'. It does not mention whether deletion is permanent, if any cascading effects occur, or the role of the 'confirmProductionWrite' parameter (only documented in schema). This is insufficient for a destructive operation.
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 a single concise sentence, but it is overly terse, omitting important details. While there is no wasted text, the lack of substance prevents a higher score.
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 absence of an output schema and annotations, the description should cover return behavior (e.g., success response) and safety concerns (e.g., production write confirmation). It fails to provide a complete mental model for the agent.
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 all parameters are documented in the schema. The description adds no additional meaning beyond 'Delete a popup by ID.' Thus, it meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Delete) and the resource (popup) and specifies the identifier (by ID). It succinctly distinguishes this tool from sibling CRUD tools like thincms_create_popup, thincms_get_popup, thincms_update_popup.
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?
No guidance is provided on when to use this tool versus alternatives, prerequisites (e.g., existence of the popup), or consequences of deletion. The description is purely declarative with no contextual usage advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a blog post by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Post ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behaviors. It says 'permanently delete' (irreversible) but fails to mention important traits: the need for production confirmation (confirmProductionWrite parameter), site switching behavior, or any side effects. This leaves the agent underinformed.
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 very concise (one sentence), but it sacrifices completeness. It front-loads the key action but omits critical context. Every word is earned, but more is needed.
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 (3 parameters, no output schema, many siblings), the description is insufficient. It lacks context about site switching, production safeguards, and expected behavior, making it hard to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters. The description adds no new meaning beyond 'by ID' (which is redundant). It does not mention optional parameters like siteId or confirmProductionWrite.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action (delete), resource (blog post), and identifier method (by ID). It distinguishes this from sibling delete tools like thincms_delete_course and thincms_delete_page by specifying the resource type.
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?
No guidance is provided on when to use this tool versus alternatives (e.g., other delete tools). There is no mention of prerequisites, context (like site selection), or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a quiz and all its questions and attempts.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Quiz ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While no annotations are provided, the description discloses cascading deletion (questions and attempts), which is important behavioral context. However, it omits details about irreversibility, permissions, or production safety implications.
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 concise sentence with no extraneous words, front-loaded with the core action and scope. Every word is necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (delete operation) and 100% schema coverage, the description is nearly complete. It lacks mention of the return value or error conditions, but these are minor gaps.
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 parameters are already well-documented. The description does not add additional meaning beyond what the schema provides, meeting the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Delete'), resource ('a quiz'), and scope ('all its questions and attempts'), distinguishing it from other delete tools like thincms_delete_lesson or thincms_delete_workbook.
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?
No explicit guidance on when to use this tool versus alternatives, nor any exclusion criteria. The description only states the action without contextual usage advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a question from a quiz.
| Name | Required | Description | Default |
|---|---|---|---|
| quizId | Yes | Quiz ID (required) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| questionId | Yes | Question ID (required) | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden of behavioral disclosure. However, it only states 'delete' without clarifying destructive implications, required permissions, side effects (e.g., affecting quiz results), or the presence of the confirmProductionWrite parameter. The description fails to add critical behavioral context beyond the obvious.
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 a single sentence, making it concise. However, it is too brief to convey necessary context; it sacrifices informativeness for brevity. An ideal description would be slightly longer but still focused.
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 4 parameters (including cross-cutting siteId and confirmProductionWrite) and no output schema or annotations, the description is incomplete. It omits important details such as the effect of the siteId override, the requirement for confirmProductionWrite in production, and what happens upon success or error. The agent lacks sufficient context to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with all 4 parameters documented. The description adds no additional meaning beyond the schema, so it meets the baseline. However, it does not explain relationships (e.g., the interplay of quizId and questionId) or any usage patterns, keeping it at a 3.
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 'Delete a question from a quiz' uses a specific verb and resource, clearly distinguishing it from sibling tools like thincms_delete_quiz (deleting an entire quiz) or thincms_delete_lesson (deleting a lesson). It leaves no ambiguity about the tool's function.
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 provides no guidance on when to use this tool vs alternatives, nor does it mention prerequisites or exclusions. The agent is left without context on proper usage, which is a significant gap for a delete operation in a content management system.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a redirect by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Redirect ID (required) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description fails to disclose that this is a write operation requiring the confirmProductionWrite parameter for production sites. The schema mentions this, but the description should alert the agent to safety requirements.
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?
Extremely concise at one sentence. While front-loaded, the brevity omits important safety context. Could benefit from a second sentence about production write acknowledgment.
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?
Lacks critical context: no mention of return value, side effects, or the need for confirmProductionWrite on production sites. Schema covers params but overall behavior is under-described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for all parameters (id, siteId, confirmProductionWrite). The tool description adds no extra parameter information, 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?
The description 'Delete a redirect by ID' clearly states the verb (delete) and the resource (redirect), specifying the identifier used. It is specific and distinct from sibling tools which operate on other resources.
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?
No guidance on when to use this tool versus alternatives (e.g., thincms_update_redirect, thincms_import_redirects). No mention of prerequisites like retrieving the ID beforehand or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a sequence and all its steps.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Sequence ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the cascading deletion of steps, which is important behavioral info. However, it does not mention the confirmProductionWrite parameter or any other safety considerations, and no annotations are provided to compensate.
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 a single, front-loaded sentence with no fluff. It efficiently conveys the core purpose.
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 description is minimal and lacks detail on error handling, dependencies, or production safety. Given the complexity of cascading delete and the presence of confirmProductionWrite, more context is needed.
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 description adds no extra parameter meaning. The schema already describes id, siteId, and confirmProductionWrite adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Delete a sequence and all its steps,' specifying the verb and resource, and it distinguishes from sibling tool delete_sequence_step which only removes a single step.
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?
No guidance is provided on when to use this tool vs alternatives like delete_sequence_step or other delete tools. The description does not mention prerequisites or when to prefer this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a step from a sequence.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| stepId | Yes | Step ID | |
| sequenceId | Yes | Sequence ID | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose destructive nature, irreversibility, and any side effects (e.g., reordering). It only says 'Delete', which is implied but lacks detail.
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?
Very concise at one sentence, no fluff. However, given the lack of annotations, slightly more context could be justified without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is incomplete for a delete operation with 4 parameters and no output schema. It omits behavioral context, prerequisites, and guidance on production write confirmation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters. The tool description adds no additional meaning beyond the schema, so baseline score of 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?
The description 'Delete a step from a sequence' clearly states the action and the resource, distinguishing it from sibling tools like add_sequence_step or update_sequence_step.
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?
No guidance on when to use this tool versus alternatives (e.g., update_sequence_step, delete_sequence), or what conditions must be met before deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a form submission by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| formId | Yes | Form ID (required) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| submissionId | Yes | Submission ID to delete | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden. It only states 'Delete' without disclosing whether the deletion is permanent, permissions needed, side effects, or interaction with production safeguards. The confirmProductionWrite parameter hints at safety but the description does not address it.
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 a single, clear sentence that efficiently states the purpose. It is concise, though it could benefit from slight expansion for behavioral context without becoming verbose.
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 presence of 4 parameters including a production-write confirmation, the description lacks context about usage flow, return values (no output schema), and the destructive nature. It is under-specified for reliable agent usage.
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 description adds no additional meaning beyond what the schema already provides for each parameter. The baseline score of 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 'Delete a form submission by ID' clearly states the verb (delete) and resource (form submission), and distinguishes it from sibling tools like thincms_list_submissions or thincms_export_submissions_csv.
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?
No guidance is provided on when to use this tool vs alternatives, prerequisites (e.g., submission must exist), or when not to use it. The description is minimal and leaves the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a subscriber by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The subscriber ID to delete | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the full burden of behavioral disclosure. While 'Delete' implies a destructive mutation, the description does not detail side effects (e.g., cascade, irreversibility) or prerequisites (e.g., permissions). The confirmProductionWrite parameter hints at production safety, but the description fails to explain this.
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 a single concise sentence that clearly states the purpose. It is appropriately front-loaded, but it could include more contextual information without becoming verbose. Every word 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?
Given the destructive nature of the operation (no annotations) and three parameters including confirmProductionWrite, the description lacks completeness. It does not mention permanence, production write acknowledgment, or the siteId parameter's role, leaving the agent without sufficient context to use the tool safely.
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 fully documents each parameter. The description adds no additional meaning beyond what the schema provides, meeting the baseline of 3 per calibration rules.
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 'Delete a subscriber by ID' clearly specifies the verb (Delete) and resource (subscriber) with the key identifier (ID). It distinguishes this tool from sibling tools like thincms_list_subscribers or thincms_set_subscriber_password by naming the resource and action.
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?
No guidance is provided on when to use this tool versus alternatives (e.g., deactivating a subscriber or using a different tool). Prerequisites, such as the subscriber existing or the irreversibility of deletion, are not mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a tag by ID. Removes the tag from all posts.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Tag ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses the cascade effect (removes from all posts), which is helpful. However, it does not mention permissions, irreversibility, or what happens on error or success.
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, front-loaded sentences with no fluff. Every word 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 delete tool, the description is adequate but missing details like success response, idempotency, or handling of non-existent tags. No output schema, so more context would help.
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 description does not add value beyond the schema. The 'id' parameter is mentioned, but siteId and confirmProductionWrite are not elaborated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Delete) and resource (tag by ID), and adds the side-effect of removing the tag from all posts, distinguishing it from other delete tools like thincms_delete_post.
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?
No guidance on when to use this tool versus alternatives like thincms_delete_category or thincms_update_tag. Prerequisites or common use cases are not mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a Tool. Cascades to all ToolData rows, ToolAiUsage rows, and end-user sessions scoped to it.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Tool ID or slug | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description effectively discloses permanence and cascading behavior (ToolData, ToolAiUsage, end-user sessions). It does not mention authentication or production write confirmation, but the schema covers the latter.
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 a single, well-structured sentence that efficiently conveys the core action and side effects.
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 description explains the cascade behavior adequately. It could mention the confirmProductionWrite requirement for production sites, but overall it is complete given the schema covers parameters and no output schema exists.
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 description need not repeat parameter details. The description does not add meaning beyond the schema, which is acceptable at this coverage level.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it permanently deletes a Tool and cascades to associated rows and sessions, distinguishing it from related siblings like thincms_delete_tool_data which only deletes data rows.
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 use for permanent removal but does not explicitly state when to use this vs. alternatives like thincms_delete_tool_data, nor when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a single data key. Deletes only the caller's scope — with subscriberId, the per-user value; without, the tool-global value.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Tool ID or slug | |
| key | Yes | Data key | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| subscriberId | No | End-user Subscriber ID | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It explains the scoping behavior but does not mention error handling (e.g., deleting non-existent key), idempotency, or the destructive nature (though implied). Lacks details on side effects or safety considerations.
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 unnecessary words. Efficiently conveys the core function and scoping nuance.
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 description covers the deletion behavior and scoping but omits important context: what happens after deletion (no output schema), the role of confirmProductionWrite for safety, and how siteId affects scope. Given 5 parameters and no output schema, more detail would be beneficial.
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 meaningful context for subscriberId (caller's scope, per-user vs. tool-global) but does not add new information for id, key, siteId, or confirmProductionWrite beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Delete a single data key') and distinguishes scoping behavior with/without subscriberId. It differentiates from sibling tools like get, set, list tool 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?
Provides clear guidance on when to include subscriberId for per-user deletion vs. omitting it for tool-global deletion. However, it does not explicitly state when not to use this tool or mention alternatives like thincms_set_tool_data with empty value.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a workbook and all its learner responses. This is destructive — there is no soft delete.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Workbook ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses destructive nature and no soft delete, which is good. However, it omits details about confirmProductionWrite parameter, authentication requirements, or response behavior, leaving gaps for an AI agent.
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, directly stating the core action and a key behavioral note. No unnecessary words, and the critical information is front-loaded.
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 delete tool with no output schema and no annotations, the description covers the essential destructive behavior. However, it lacks context on the siteId and confirmProductionWrite parameters, which are important for correct usage in multi-tenant environments. This is a notable gap.
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?
All three parameters are described in the input schema (100% coverage). The description adds no additional parameter-specific meaning beyond the schema. Baseline score of 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 clearly states the action (delete) and the resource (workbook), specifying that learner responses are also removed. It distinguishes itself from sibling tools like thincms_create_workbook by emphasizing irreversibility.
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?
No explicit guidance on when to use this tool versus alternatives. While the description implies permanent deletion, it does not mention prerequisites, when not to use, or suggest any alternatives (e.g., soft delete options, though none exist).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export a learner's full course portfolio (every workbook in module order) as PDF or Markdown. Pass outputPath for PDF (required) or to save the Markdown to disk.
| Name | Required | Description | Default |
|---|---|---|---|
| format | Yes | Output format | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| userId | Yes | Learner user ID (required) | |
| courseId | Yes | Course ID (required) | |
| outputPath | No | Local file path to write the export to. Required for PDF. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It mentions file writing but does not disclose whether the operation is destructive, requires specific permissions, or what the return value is. The confirmProductionWrite parameter is not explained in description.
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 concise (two sentences) and front-loaded with the main purpose. Minor redundancy could be trimmed, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters and no output schema, the description is incomplete. It does not mention return behavior, error conditions, or the important confirmProductionWrite safety context. Without annotations, more detail is needed.
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 each parameter. The description adds minor clarification about outputPath conditional requirement. Baseline 3 is appropriate as description adds little beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool exports a learner's full course portfolio as PDF or Markdown, specifying the resource (learner's course portfolio), action (export), and output formats. It distinguishes from sibling tools like thincms_export_workbook_response by highlighting 'every workbook in module order'.
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 gives some guidance on parameters (outputPath required for PDF), but does not explicitly state when to use this tool vs. alternatives like exporting individual workbooks. It lacks mention of prerequisites or excluded scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export all submissions for a form as CSV data.
| Name | Required | Description | Default |
|---|---|---|---|
| formId | Yes | Form ID (required) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must bear full behavioral disclosure. It does not disclose any side effects (e.g., file creation, data download), authorization requirements, rate limits, or handling of large datasets. The description is too minimal for a mutation-like export operation.
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 a single, clear sentence with no waste. It could be slightly improved by front-loading key details, but it is appropriately sized and immediately understandable.
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 tool is simple (export submissions as CSV) and no output schema exists, so the description should compensate by clarifying the format of the returned data (e.g., direct CSV output vs. download URL). It is adequate but not fully complete; for example, it doesn't mention that it returns CSV content rather than a file 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?
Schema description coverage is 100%, so baseline is 3. The description adds no additional meaning beyond the schema: it does not explain how formId, siteId, or confirmProductionWrite affect the export. The schema already documents these parameters.
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 uses a specific verb-resource pair: 'Export all submissions for a form as CSV data.' It clearly identifies what data is exported (submissions for a form) and the format (CSV). This distinguishes it from sibling tools like thincms_list_submissions (which likely returns JSON) and other export tools for different entities (subscribers, workbooks).
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 provides no guidance on when to use this tool instead of alternatives such as thincms_list_submissions, which might also retrieve submission data but in a different format. There are no when-not-to-use instructions or context about prerequisites (e.g., needing formId).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export all subscribers as CSV data.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It does not specify whether the CSV is returned directly, stored as a file, or triggers a download. The confirmProductionWrite parameter hints at potential write behavior, but the description does not clarify side effects or authentication needs.
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 extremely concise (6 words) but lacks structure and important details. It sacrifices completeness for brevity.
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 no output schema and no annotations, the description should at minimum state what the tool returns (e.g., CSV string, file URL). It fails to explain the output format or behavior, leaving the agent uninformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The tool description adds no additional insight beyond the schema, so 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 clearly states the action 'Export', the resource 'subscribers', and the output format 'CSV'. It is distinct from sibling tools like thincms_export_submissions_csv which target different resources.
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?
No guidance on when to use this tool versus alternatives such as thincms_list_subscribers. No mention of preconditions or when not to use. The description provides no usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export a single learner's workbook response as PDF or Markdown. Pass outputPath to write the file to disk (required for PDF; recommended for Markdown). Without outputPath, Markdown is returned inline.
| Name | Required | Description | Default |
|---|---|---|---|
| format | Yes | Output format | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| userId | Yes | Learner user ID (required) | |
| outputPath | No | Local file path to write the export to. Required for PDF. | |
| workbookId | Yes | Workbook ID (required) | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses export formats and file writing behavior but lacks details on side effects, authentication needs, rate limits, or whether the operation is destructive. The confirmProductionWrite parameter hints at write implications but is not explained in the description.
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 two sentences long, front-loading the purpose and then explaining the key usage detail. Every sentence earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters) and lack of output schema, the description covers the core functionality and outputPath behavior. However, it could clarify what is returned when writing to disk (e.g., success message or nothing) and explicitly mention required parameters.
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 value by clarifying the relationship between outputPath and format (required for PDF, optional for Markdown) and the inline return behavior, going beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool exports a single learner's workbook response as PDF or Markdown, specifying the verb 'export' and the resource. This distinguishes it from sibling tools like thincms_export_workbook_responses_csv (bulk CSV export) and thincms_export_course_portfolio.
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 provides context on when to use outputPath (required for PDF, recommended for Markdown) and behavior without it (inline Markdown). However, it does not explicitly state when to use this tool over alternatives or mention exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export every learner response for a workbook as CSV (admin). Pass outputPath to save to disk; otherwise the CSV body is returned inline.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| outputPath | No | Local file path to write the CSV to | |
| workbookId | Yes | Workbook ID (required) | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It notes 'admin' and the output behavior, but does not disclose potential file overwrites, large inline responses, or production write implications beyond what the parameter confirmProductionWrite hints. The 'admin' label is minimal.
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 a single, concise sentence that front-loads the core action. Every word is useful, with no 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?
No output schema is provided, so the description should clarify the return format. 'CSV body is returned inline' is vague; it does not specify if it is a string, file, or how large payloads are handled. Additionally, it does not differentiate from similar exports (e.g., thincms_export_submissions_csv) beyond the resource.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all parameter descriptions (100% coverage). The description adds context for outputPath ('save to disk vs inline') but does not add significant meaning beyond the schema for other parameters. 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 specifies the exact action ('Export every learner response for a workbook as CSV') and includes the admin scope. It clearly distinguishes from the sibling thincms_export_workbook_response, which exports a single response.
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 mentions two usage modes (save to disk vs inline) but does not explicitly compare to sibling tools like thincms_export_workbook_response or thincms_export_submissions_csv. No guidance on when to use this export over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate optimized WebP image variants for all images in the media library that don't have them yet. Creates thumbnail (400px), medium (800px), and large (1200px) WebP versions. Admin-only.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool only creates variants for images without them, and lists the three sizes. It also notes the admin-only restriction. However, it does not mention whether the operation is reversible, if it is synchronous or asynchronous, or any performance implications. The behavioral details are adequate but not comprehensive.
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 extremely concise: three sentences, each adding distinct value (purpose, sizes, restrictions). Front-loaded with the key verb and resource. No extraneous or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of two well-documented parameters and the absence of output schema or annotations, the description provides sufficient context for an agent to understand when and how to call it. It could be improved by noting what the tool returns (e.g., summary of generated variants) or any limitations (e.g., only processes images, not other media types). Nevertheless, it is largely complete for a straightforward batch operation.
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 description does not mention any parameters. However, the input schema has 100% coverage, so both parameters (siteId and confirmProductionWrite) are already documented in the schema. The description adds no extra semantic meaning beyond what the schema provides, resulting in a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: generating WebP image variants (thumbnail, medium, large) for all images in the media library that lack them. It explicitly names the action ('Generate') and the resource ('media variants'), and distinguishes itself from sibling media tools like upload, update, or delete.
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 for batch generation of missing WebP variants and flags 'Admin-only' as a restriction. However, it does not explicitly state when to use this tool versus alternatives (e.g., uploading already-optimized images, or manually generating variants via update_media). No guidance on prerequisites or consequences.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a campaign by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Campaign ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description should disclose behavioral traits. It does not state that this is a read-only operation, what the return value looks like, or any side effects. The confirmProductionWrite parameter is mentioned in the schema but not clarified in the description, which could confuse an agent.
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 a single, clear sentence with no superfluous information. It is appropriately sized for a simple retrieval tool and front-loads the essential action.
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 description does not explain the return value or output format, which is critical for a get tool. Since there is no output schema, the description should indicate what data is returned (e.g., full campaign object). This omission leaves the agent without necessary context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the schema already explains each parameter. The tool description adds no additional meaning beyond the schema, meeting the baseline but not exceeding it.
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 uses a specific verb 'Get' and resource 'campaign' with the identifier 'by ID', clearly stating the tool's purpose. It distinguishes it from siblings like thincms_list_campaigns (list) and thincms_create_campaign (create).
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 provides no explicit guidance on when to use this tool versus alternatives. While the purpose is obvious for a retrieval tool, it does not mention when to use it over other similar tools for different resources, nor does it give any prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single collection by ID, including all its items.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Collection ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It does not state whether the tool is read-only or safe, nor what happens if the collection does not exist. The confirmProductionWrite parameter description suggests it's a read operation, but the main description lacks clarity.
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 a single sentence with 12 words, front-loaded with the core purpose. Every word is necessary.
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 no output schema, the description partially compensates by noting items are included. However, it does not clarify other collection fields, error states, or provide guidance on using the optional parameters.
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 parameter descriptions are provided, so the description adds little beyond the schema. The note about 'including all its items' gives output context but does not enhance parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Get), the target resource (a single collection by ID), and what it returns (including all its items). It distinguishes from siblings like thincms_list_collections which lists collections.
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 does not provide explicit guidance on when to use this tool versus alternatives (e.g., thincms_list_collections). Context is implied by the tool name and sibling list, but no when-not-to-use advice is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single content block by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Content block ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. The word 'Get' suggests a read-only operation, but this is not explicitly confirmed. The schema includes confirmProductionWrite parameter, which might confuse agents into thinking this tool could write; the parameter description says it's ignored for non-write calls, but the tool description does not clarify that it is a safe read operation. More transparency about idempotency and side effects is needed.
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 a single concise sentence with no wasted words. It is appropriately sized for a simple get tool.
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?
No output schema exists, so the description should explain what the tool returns. It only says 'Get a single content block by ID' without specifying the structure or fields of the returned block. Error conditions or potential issues are not mentioned. The description is too sparse for an agent to fully understand the tool's output.
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%, with each parameter having a clear description. The tool description adds no additional meaning beyond the schema. Baseline 3 is appropriate since the schema already does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a single content block by ID' with a specific verb and resource. It is immediately distinguishable from sibling tools like list, create, update, delete, which have distinct purposes.
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 provides no explicit guidance on when to use this tool versus alternatives like thincms_list_content_blocks. However, the name 'get' implies retrieving one specific block, which is a reasonable default expectation. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single course by ID, including its modules, lessons, and quizzes.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Course ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It adds behavioral context by mentioning included nested resources (modules, lessons, quizzes), but lacks details about side effects, authorization needs, or rate limits. The description is adequate but not rich.
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 a single sentence with 12 words, containing no filler. It efficiently communicates the tool's core function.
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 absence of an output schema, the description includes useful hints about the return structure (modules, lessons, quizzes). However, it could be more explicit about the response format or confirm that it is a read-only retrieval.
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 parameters are fully documented in the schema. The description adds no extra meaning beyond 'by ID' for the required parameter, providing no additional context for siteId or confirmProductionWrite.
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 uses a specific verb ('Get') and resource ('a single course by ID'), clearly stating the operation. It also distinguishes from sibling tools like thincms_list_courses by specifying that it returns nested modules, lessons, and quizzes. This leaves no ambiguity about the tool's purpose.
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 for retrieving detailed course data but does not explicitly state when to use this tool versus alternatives like thincms_get_lesson or thincms_get_quiz. There is no guidance about when not to use it or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single form by ID with full field definitions and configuration.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Form ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only says 'Get', but the input schema includes 'confirmProductionWrite'—a parameter typically required for mutations—which creates confusion about whether this tool is read-only or might write. No annotations exist to clarify safety traits, and the description does not address this inconsistency or disclose any side effects.
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 a single, concise sentence that directly states the purpose. It is not verbose, though it lacks structure (e.g., bullet points) and could benefit from separating purpose from details. Still, it is efficient and front-loaded.
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?
No output schema exists, so the description helpfully mentions 'full field definitions and configuration' for return values. However, it omits clarifying the conflicting 'confirmProductionWrite' parameter, which is a notable gap for a supposedly read-only tool. For a simple retrieval tool, the description is adequate but not comprehensive.
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 parameters clearly. The description adds no extra meaning beyond identifying 'by ID' (which is obvious). The potential confusion about 'confirmProductionWrite' is not resolved, but the description does not mislead about parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get a single form'), the identifier method ('by ID'), and the scope ('with full field definitions and configuration'). It is specific and distinguishes from sibling tools like thincms_list_forms (list) and thincms_create_form (create).
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 provides no guidance on when to use this tool versus alternatives (e.g., thincms_list_forms for listing forms, thincms_get_form vs thincms_get_post for similar patterns). There's no mention of prerequisites or context for selecting this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the site's email platform integration configuration.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must fully convey behavioral traits. It states 'Get' (read-only) but does not explain the presence of confirmProductionWrite in a GET context, nor does it mention authentication, rate limits, or side effects.
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 a single sentence, which is concise but under-specified for a tool with two optional parameters. It lacks efficiency in conveying critical context beyond the bare purpose.
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 description omits crucial context such as return value format, side effects, and clarification of confirmProductionWrite's role in a GET call. Given no output schema and 100% parameter coverage, the description should compensate but does not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with detailed parameter descriptions. The tool description adds no additional meaning beyond the schema, so a baseline score of 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 clearly states the verb 'Get' and resource 'email platform integration configuration,' making the tool's purpose unambiguous. It distinguishes well from sibling tools like thincms_create_integration or thincms_update_integration.
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?
No guidance is provided on when to use this tool vs. other integration tools (e.g., test or sync). The context is clear but lacks exclusions or alternatives, leaving the agent to infer that it is a read-only operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single lead magnet by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Lead magnet ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description bears full responsibility. It states 'Get' implying a read operation but confirms no behavioral traits like idempotency, authorization needs, or side effects. The description does not add beyond the inferred read nature.
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 very concise (5 words) and front-loads the purpose. No extra sentences. However, it may be too brief for optimal agent comprehension, lacking structured sections.
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?
No annotations, no output schema, and the description does not mention return value or response format. For a 'get' operation, the output is expected to be the lead magnet object, but this is not stated. The description is incomplete for an agent to fully understand the tool's context.
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 parameter descriptions in the schema are detailed (e.g., siteId and confirmProductionWrite). The description does not add extra meaning beyond 'by ID', but the schema already covers parameter semantics adequately.
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 uses a specific verb 'Get' and identifies the resource 'lead magnet' and the method 'by ID'. It clearly indicates what the tool does, though it does not differentiate from sibling 'get' tools beyond the resource name.
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?
No guidance on when to use this tool versus alternatives (e.g., thincms_list_lead_magnets or thincms_update_lead_magnet). No context on prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single lesson by ID, including its attachments.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Lesson ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a safe read operation, but with no annotations, it lacks explicit statements about side effects (none expected) or error behavior (e.g., missing ID). The parameter descriptions provide some behavioral context for siteId and confirmProductionWrite, which helps.
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 a single, concise sentence that conveys the essential purpose without redundancy. Every word is meaningful.
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 tool with a single required parameter and no output schema, the description is functional but lacks details about the return structure. The inclusion of attachments is helpful, but more context (e.g., pagination, error handling) would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds no parameter details. The parameter descriptions in the schema are detailed for siteId and confirmProductionWrite, but the tool description itself does not elaborate on parameters. 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 clearly states the verb ('Get'), the resource ('lesson'), and the inclusion of attachments. This distinguishes it from tools like thincms_get_lesson_attachment_url, but it could be more specific about what fields are returned beyond attachments.
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?
No guidance is provided on when to use this tool versus alternatives (e.g., thincms_get_lesson_attachment_url for attachment URLs). There is no context about prerequisites or execution conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the download URL for a lesson attachment. Returns the URL path — append to your base URL to download.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| lessonId | Yes | Lesson ID (required) | |
| attachmentId | Yes | Attachment ID (required) | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description partially discloses behavior by noting the tool returns a URL path (not full URL) requiring base URL appending. However, it does not confirm the operation is read-only (though implied by 'Get'), lacks idempotency or safety guarantees, and omits potential failures like missing attachment.
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 wasted words. The purpose and result format are clearly stated upfront, making it easy for an agent to parse and act on.
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 retrieval tool with no output schema, the description adequately covers the return value and usage: it explains that the result is a URL path to be appended to a base URL. This is sufficient for an agent to use the result correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no new meaning beyond the schema; it merely mentions the required parameters without elaborating on format or constraints not already in the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a download URL for a lesson attachment, using the specific verb 'Get' and the resource 'lesson attachment'. It distinguishes itself from sibling tools like thincms_upload_lesson_attachment and thincms_delete_lesson_attachment by focusing on retrieval.
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?
No guidance is provided on when to use this tool versus alternatives such as thincms_get_lesson for attachment metadata or other attachment operations. There is no mention of prerequisites, context, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single media item by ID with full metadata. The response includes a variants field with optimized WebP versions (thumbnail 400px, medium 800px, large 1200px) when available.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Media ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the response includes a 'variants' field with detailed version information (dimensions, WebP format). It does not mention side effects (none expected for a read) or auth requirements, but provides meaningful behavioral context beyond the 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?
The description is two sentences, both highly informative. The first sentence states the core purpose, the second adds a key output detail. No fluff or repetition. Ideal for quick agent consumption.
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?
No output schema exists, but the description compensates by describing the 'variants' field. It adequately covers what the agent needs to know for a simple retrieval tool. Missing details like error handling or pagination are not critical here.
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%—all three parameters have descriptions. The tool description does not add additional parameter semantics beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear verb ('Get') and resource ('single media item by ID'), and distinguishes itself from sibling tools like thincms_list_media (list) and thincms_upload_media (create). It also specifies 'full metadata' and highlights the variants field, which is unique to this tool.
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 clearly states the tool retrieves a single media item by ID, implying usage when a specific item's details are needed. It does not explicitly state when to avoid using it or provide alternatives, but the context against siblings makes it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single static page by ID, including full HTML content.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Page ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description states read-only nature but omits side effects, error handling (e.g., missing page), permissions, or rate limits. With no annotations, agent lacks critical behavioral 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?
Single 11-word sentence with no redundancy. Front-loaded with essential 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?
Minimal context: lacks response structure (no output schema), error states, or usage constraints. Adequate for a simple read but could be improved.
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?
All three parameters have schema descriptions (100% coverage), so baseline is 3. Description adds no extra meaning; parameters are self-documented in 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?
Description clearly states 'Get a single static page by ID' with specific verb-resource pairing and includes 'full HTML content'. Differentiates from listing/creating/updating 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?
No guidance on when to use this tool versus alternatives like thincms_list_pages or thincms_get_post. No mention of prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single popup by ID with full configuration.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Popup ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It does not mention that this is a read-only operation, any authentication requirements, or explain the presence of confirmProductionWrite param in a GET call.
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?
Single sentence with no wasted words, clearly stating the core purpose.
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 description is sufficient for a simple GET popup tool, but it lacks guidance on parameter usage and the meaning of 'full configuration'. No output schema exists, so return values are not explained.
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 no additional meaning beyond the schema; it does not elaborate on siteId or confirmProductionWrite parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Get', resource 'single popup', and qualifier 'by ID with full configuration', distinguishing from sibling list, create, update, and delete tools.
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 implied (use when you have an ID), but no explicit when-to-use or when-not-to-use guidance is given, nor are alternatives like thincms_list_popups mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single blog post by ID, including full HTML content, author, categories, and tags.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Post ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It discloses that the return includes full HTML content, author, categories, and tags, giving insight into the response shape. For a read-only GET, this is adequate; no side effects or permissions are omitted.
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?
Single sentence, no extraneous words. Front-loads the main purpose and key included fields. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with full schema coverage and a concise description explaining the returned data, it is complete. No output schema exists, but the description compensates by listing returned fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with well-described parameters. The description does not add any parameter information beyond what the schema provides, so 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 clearly states it retrieves a single blog post by ID and lists key included fields (full HTML content, author, categories, tags). This distinguishes it from sibling tools like thincms_list_posts (list all) and thincms_get_post_preview_url (preview URL).
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 when you need a specific post by ID, but lacks explicit guidance on when to use this vs alternatives (e.g., thincms_list_posts for multiple posts, thincms_get_post_preview_url for preview). No exclusions or context-specific notes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a signed preview URL for a blog post. Works for any status (draft, scheduled, future-dated, published). The URL is valid for 72 hours and requires no authentication to view. Use this after creating or updating a post to verify how it looks on the live site.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Post ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral disclosure. It reveals the URL's validity period (72 hours), no authentication requirement, and compatibility with any post status (draft, scheduled, future-dated, published). It does not mention potential side effects like logging or rate limits, but the disclosed traits are sufficient for expected use.
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 three sentences long, front-loaded with the core purpose, and each sentence provides essential information without redundancy or verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no output schema, few parameters), the description covers purpose, behavior, usage guidelines, and parameter implications adequately. It does not specify the exact response format, but 'signed preview URL' implies a URL string, which is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with detailed descriptions for all three parameters, including usage patterns for siteId and confirmProductionWrite. The tool description does not add extra semantic value beyond the schema, so the baseline score of 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?
The description clearly states the tool retrieves a signed preview URL for a blog post, specifying the resource (blog post) and action (get preview URL). However, it does not explicitly differentiate from the sibling tool 'thincms_get_preview_url', though the name suggests it's post-specific.
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 advises using this tool after creating or updating a post to verify appearance on the live site, providing clear usage context. It does not mention when not to use it or alternatives, but the guidance is specific and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full preview URL for a preview token. The URL can be opened in a browser to view the preview — no authentication required.
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | Preview token from thincms_create_preview | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that no authentication is required to view the URL, which is helpful. However, it does not discuss error cases, token expiration, or confirm that the operation is read-only.
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 two sentences, immediately stating the action in the first sentence and adding a key behavioral note in the second. No extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no output schema and three well-documented parameters, the description covers the essential: getting a preview URL and its accessibility. It omits token validity or error handling, but is mostly sufficient for task execution.
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 3 applies. The parameter descriptions in the schema are detailed (e.g., token sourced from thincms_create_preview, siteId concurrency note). The tool description itself adds no extra parameter information, but the schema adequately covers semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets a full preview URL for a preview token, identifying the verb and resource. It distinguishes from thincms_create_preview which creates the token, but does not explicitly differentiate from the similar sibling thincms_get_post_preview_url.
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 after creating a preview token and notes no authentication required, but does not provide explicit when-to-use or when-not-to-use guidance, nor mention alternatives like thincms_get_post_preview_url.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single quiz by ID, including its questions with correct answers.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Quiz ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden. It discloses that the tool returns questions with correct answers, which is valuable. It does not explicitly state it's read-only, but that is implied by 'Get'. No contradictions.
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 a single, concise sentence that efficiently communicates the tool's purpose and return content without extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get tool with one required parameter and 100% schema coverage, the description is mostly complete. It mentions the key return data (questions with correct answers). It lacks details on error handling or output format, but that's acceptable given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for all three parameters (id, siteId, confirmProductionWrite). The tool description adds no additional insight beyond the schema, so 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 clearly states 'Get a single quiz by ID, including its questions with correct answers.' It specifies the verb (Get), resource (quiz), and key inclusion (questions with correct answers). This distinguishes it from sibling tools like thincms_list_courses or thincms_create_quiz.
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 purpose implies when to use: when you need a specific quiz by ID. However, it lacks explicit guidance on when not to use or alternatives, but given the straightforward nature, the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single redirect by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Redirect ID (required) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description bears full responsibility for behavioral disclosure. It states 'Get', implying a read operation, but does not confirm non-destructiveness, discuss permissions, or what happens on failure (e.g., not found). The existence of the confirmProductionWrite parameter in the schema, which is for write operations, is not addressed.
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 a single, efficient sentence front-loading the core purpose. While it could be more informative, it avoids extraneous words.
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 get-by-ID tool with well-documented parameters and no output schema, the description is mostly adequate. It could mention that the return value is the redirect object, but the lack of output schema reduces the need.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema; the schema already provides detailed descriptions for siteId and confirmProductionWrite.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'redirect', and the identifier 'by ID'. This distinguishes it from sibling tools like thincms_list_redirects (list all) and thincms_create_redirect (create).
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 when you have a specific redirect ID, but it does not provide explicit guidance on when to use this tool versus alternatives (e.g., use thincms_list_redirects to find an ID first). No exclusions or context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single review by ID, including full text, sentiment fields, and drift notes if drift was detected.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Review ID. | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses the output includes full text, sentiment fields, and drift notes, indicating a read-only operation. It does not mention side effects, but for a get operation this is sufficient.
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 a single sentence that captures the essential purpose and return content. It is front-loaded and concise without any superfluous text.
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 no output schema, the description adequately hints at return values (text, sentiment, drift notes). It could specify more about drift notes format or pagination, but for a simple get operation it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The tool description adds no additional parameter meaning beyond what the schema already provides, so baseline score of 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 clearly states the verb 'Get', the resource 'a single review by ID', and lists included fields ('full text, sentiment fields, and drift notes'), distinguishing it from sibling tools like thincms_list_reviews.
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 implicitly indicates this is for retrieving a specific review by ID, and the sibling list provides context for when to use this over listing. No explicit when-not or alternatives, but the purpose is clear enough for correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current reviews + AI configuration for the active site, plus recipient list and last-sync status. Admin-only. Secrets are echoed only as has*Key booleans, never as plaintext.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that 'Secrets are echoed only as has*Key booleans, never as plaintext', a key security behavior. Also mentions admin-only restriction and what the response includes, but does not discuss potential side effects or rate limits. Overall good transparency for a read-only operation.
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 two sentences long, front-loading the core purpose and then adding behavioral notes. Every word adds value; no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with no output schema, the description adequately explains what is returned (reviews+AI config, recipient list, last-sync status) and a security concern. It lacks mention of error modes or pagination, but these are likely unnecessary given the tool's nature. Nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is well-documented in the schema. The description does not add any parameter-level meaning beyond what the schema already provides, meeting baseline expectations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get the current reviews + AI configuration for the active site', specifying the verb and resource. It distinguishes from sibling thincms_update_reviews_settings by emphasizing read-only and listing return components.
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 notes 'Admin-only' as a prerequisite but provides no explicit guidance on when to use this tool vs alternatives like thincms_update_reviews_settings or thincms_sync_reviews. Usage context is implied but not fully clarified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a sequence by ID, including its steps.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Sequence ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It indicates a read operation ('Get') but does not explicitly state it is read-only or side-effect-free. The parameter confirmProductionWrite is for writes but is ignored for GET, which could be clarified.
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 a single, concise sentence (7 words) that is front-loaded and contains no filler. Every word contributes to understanding the tool's purpose.
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 get tool with no output schema, the description is mostly complete: it states the resource and what is included. However, it could be slightly more complete by noting the read-only nature or that it respects the active site, though the schema covers the parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add meaning beyond the schema; the phrase 'including its steps' does not explain individual parameters. The schema already provides detailed descriptions for siteId and confirmProductionWrite.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get'), the resource ('sequence'), the identifier ('by ID'), and includes what additional data is returned ('including its steps'). This differentiates it from sibling tools like thincms_list_sequences (lists all) and thincms_create_sequence (creates).
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 does not provide explicit guidance on when to use this tool versus alternatives. The use case is implied (retrieve a specific sequence by ID), but no mention of when not to use it or alternative tools for listing (e.g., thincms_list_sequences).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get site settings: name, tagline, description, domain, logo URL, favicon URL, footer HTML, and widget configuration. Read-only via API key.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. States 'Read-only via API key' and explains that siteId allows targeting without mutating shared state. Adds context about concurrent agent sessions. Could mention rate limits or response size, but sufficient for a simple 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?
Two sentences, front-loaded with purpose and fields. No wasted words. Efficiently communicates the tool's action and its read-only nature.
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?
Lists the fields returned, which is good for a simple retrieval without output schema. Lacks return structure or error handling details, but for a straightforward settings getter it is adequate. Could mention that confirmProductionWrite is ignored for this read-only operation.
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 covers both parameters (siteId, confirmProductionWrite) with detailed descriptions. The description adds value by noting the pattern for concurrent sessions and referencing sibling tools like thincms_list_sites. Does not redundantly repeat 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?
Clearly states it retrieves site settings and lists the fields: name, tagline, description, domain, logo URL, favicon URL, footer HTML, and widget configuration. Differentiates from siblings like thincms_update_settings by being a read operation.
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?
Indicates read-only via API key, implying safe usage without side effects. Mentions siteId parameter for targeting specific tenants and references thincms_list_sites for inspection. However, lacks explicit when-not-to-use or alternatives like thincms_update_settings for writes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the site's social media links. These render in the footer via the {{social:links}} template tag.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must disclose behavioral traits. It describes a read operation, but the inclusion of confirmProductionWrite parameter suggests potential write side effects, creating inconsistency. No mention of permissions, side effects, or state changes.
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?
Extremely concise: two sentences that directly state the tool's purpose and a usage note. Fully front-loaded with no unnecessary words.
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 tool, the description covers the basic purpose, but fails to explain why confirmProductionWrite is present or how siteId interacts with active site state. Could be more complete regarding parameter usage and return details.
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?
Input schema provides full descriptions for both parameters (siteId, confirmProductionWrite) including usage rationale. The tool description adds no further value beyond the schema, so 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 clearly states the tool retrieves social media links and mentions the template tag for context. It uses a specific verb ('Get') and resource, but does not differentiate from sibling tools like thincms_update_social_links, though the verb difference makes it 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?
No guidance on when to use this tool versus alternatives or when to provide the siteId parameter. The description lacks context for usage decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single tag by ID, including associated posts.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Tag ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description adds one behavioral detail: 'including associated posts'. However, it omits common traits like read-only nature, error behavior on missing ID, or any locking/blocking considerations.
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?
Single sentence, no fluff, front-loaded with the core action. Could be slightly more structured but effective in brevity.
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 no output schema, the description lacks details about return format, pagination of associated posts, or error handling. Minimal but acceptable for a simple get operation.
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 does not add any explanatory value beyond the existing schema descriptions for parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action (get), resource (tag), identifier (ID), and what is included (associated posts). It distinguishes from siblings like thincms_list_tags (list) or thincms_create_tag (create).
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?
No guidance on when to use this tool vs alternatives like thincms_list_tags or thincms_get_post. Lacks any context for usage, prerequisites, or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the site's template: stylesheet (CSS), pageFrame (HTML wrapper with template tags like {{content}}, {{nav:header}}), and customHeadHtml.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states 'Get' implying a read operation, but does not confirm idempotency, side effects, authentication needs, or rate limits. For a GET tool, the description should at least imply read-only behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently communicates the tool's purpose and key output components. No wasted words.
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?
There is no output schema, so the description should explain the return structure. It lists the three returned components (stylesheet, pageFrame, customHeadHtml) but does not clarify that these are fields in a JSON object. It also does not mention that parameters are optional or the effect of siteId. Adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters well. The description does not add any additional meaning about the parameters (e.g., when to use siteId vs confirmProductionWrite). 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 clearly states the tool retrieves the site's template, listing specific components: CSS, pageFrame, and customHeadHtml. This is a specific verb-resource pair and distinguishes it from siblings like thincms_update_template or thincms_template_status.
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 when needing to inspect or fetch the template, but it does not explicitly state when to use this tool versus alternatives like thincms_template_status or thincms_append_css. No when-not or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single Tool by ID or slug, including the full HTML payload and config.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Tool ID or slug | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description discloses that the operation returns a full HTML payload and config, implying it is a read operation. However, it does not explicitly state read-only or idempotent behavior. For a simple get tool, this is adequate.
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 a single sentence with 14 words, front-loaded with the verb and resource. No unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 parameters, no output schema, retrieval operation), the description sufficiently covers what the tool does and returns. No obvious gaps for an agent to misuse.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all three parameters. The description does not add extra meaning beyond what the schema provides. 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 clearly states the verb (Get), resource (Tool), identification method (ID or slug), and what is returned (full HTML payload and config). It distinguishes from siblings like thincms_list_tools and thincms_create_tool.
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 for retrieval but does not provide explicit guidance on when to use this tool versus alternatives like thincms_get_tool_data or thincms_list_tools. No when-not-to-use information is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a single Tool data value. If subscriberId is provided, prefers the per-user value at that scope; otherwise reads tool-global. Falls back to tool-global if no per-user value exists.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Tool ID or slug | |
| key | Yes | Data key | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| subscriberId | No | End-user Subscriber ID to scope the read to a specific user | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It describes the read operation and fallback, but fails to address the presence of confirmProductionWrite parameter, which is unusual for a read tool and may write. This omission undermines transparency.
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 concise (three sentences) and front-loaded with the purpose. Every sentence adds value, no 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?
With no output schema, the description does not specify return format or behavior when no value exists. The 5 parameters are covered, but the tool's behavior is adequately described for basic use, though missing some details.
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% with good individual param descriptions. The tool description adds value by explaining the overall scoping logic and fallback, which is not captured in individual parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read' and the resource 'single Tool data value', and explains the scoping behavior (per-user vs tool-global). It distinguishes from sibling tools like thincms_set_tool_data and thincms_list_tool_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?
The description explains when to use subscriberId and the fallback behavior, but lacks explicit guidance on when not to use this tool or mention of alternative tools like thincms_list_tool_data for listing all keys.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a workbook by ID. Returns the workbook with its full field spec (already JSON-parsed).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Workbook ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must carry full burden. It mentions 'full field spec (already JSON-parsed)' but omits side effects, error handling, nor authentication requirements. Minimal disclosure beyond the 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?
The description is short and front-loaded with the purpose. Both sentences are necessary and clear, though it could be slightly more expansive.
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 retrieval tool, the description is mostly adequate given good schema coverage. However, it does not mention error scenarios or relationship to sibling tools, missing some completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no additional meaning beyond the parameter descriptions in the schema, such as the id or siteId purposes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a workbook by ID' with a specific verb and resource. It distinguishes from listing workbooks but does not explicitly mention alternatives like thincms_list_workbooks.
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?
No guidance on when to use this tool versus siblings such as thincms_list_workbooks or other workbook operations. The description lacks contextual usage cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Take a site live by provisioning SSL for the production domain and transitioning from 'preview' to 'live' status. Requires the production domain's DNS to be pointed to the server first. This calls the go-live endpoint which provisions Nginx config + SSL certificate.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | Yes | The site ID to take live |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes what happens internally (provisions Nginx config + SSL certificate) and the state transition. With no annotations, the description carries the burden; it covers the main behavior but doesn't mention reversibility, potential downtime, or permission requirements.
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 concise sentences with no redundant information. Each sentence adds value: first states the core action, second provides prerequisite and technical detail. Excellent structuring.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single parameter, no output schema), the description fully covers what the agent needs to know: purpose, prerequisite, and side effects. No gaps.
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?
Only one parameter (siteId) with schema description; the tool description adds context beyond the schema by explaining the prerequisite and the effects (SSL provisioning), enriching the parameter's meaning.
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?
Clearly states the tool's purpose: 'Take a site live' with specific actions (provision SSL, transition from preview to live). Distinguishes from sibling tools which are about content management, not site status changes.
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 explicit prerequisite: 'Requires the production domain's DNS to be pointed to the server first.' This guides correct usage. Could be improved by noting when not to use (e.g., if site is already live) but adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bulk import redirects from a JSON array. Existing redirects with the same sourcePath are updated (upsert).
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| redirects | Yes | Array of redirect objects to import | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description mentions upsert behavior but does not disclose that it is a write operation that may require production confirmation (confirmProductionWrite parameter). Missing details about destructive potential, rate limits, or auth needs.
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, front-loaded with purpose, then behavioral note. No filler words. Efficiently communicates core 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?
No output schema. Description covers purpose and upsert but does not mention limitations (e.g., max array size), error handling, or the need for confirmProductionWrite parameter for production sites. Adequate but with gaps.
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%, baseline 3. Description adds valuable context: 'bulk import from a JSON array' and 'upsert on same sourcePath', which are not obvious from parameter names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool does bulk import of redirects from a JSON array and specifies the upsert behavior based on sourcePath. This distinguishes it from sibling tools like thincms_create_redirect and thincms_update_redirect.
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?
No guidance on when to use this tool versus individual create/update tools or prerequisites. The description implies bulk import but does not explicitly state that it is the appropriate choice for batch operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all authors with their bios, avatars, and post counts.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry behavioral disclosure. 'List all authors' implies read-only, but does not explicitly state idempotency, side effects, or auth needs. The confirmProductionWrite parameter (typical for writes) is not explained, potentially causing confusion.
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 a single succinct sentence (9 words) with no unnecessary information. It efficiently conveys the core function without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so description should explain return format. It lists fields (bios, avatars, post counts) but lacks details on pagination, ordering, or structure. Adequate for a simple list tool with well-documented parameters, but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The tool description adds no additional parameter-level meaning beyond what the schema already provides, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all authors' with specific fields (bios, avatars, post counts). It distinguishes from create/update/delete sibling tools, but does not explicitly contrast with other list tools like thincms_list_posts. However, the tool name and resource context make the purpose 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?
No guidance on when to use this tool versus alternatives. The description lacks usage context such as prerequisites, active site behavior, or comparisons with other tools. Usage info is only found in parameter schema descriptions, not the tool description itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List email campaigns with optional status filter and pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| limit | No | ||
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| status | No | Filter by status: draft, sending, sent | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It omits whether the operation is read-only (though listing implies it), potential side effects, authentication requirements, or rate limits. The parameter confirmProductionWrite hints at writes, but the description does not clarify that this is a read operation, causing confusion.
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 a single, front-loaded sentence with no wasted words. It is appropriately concise for a straightforward list tool, though it could have added more value without becoming verbose.
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 5 parameters, lack of output schema, and no annotations, the description is insufficiently complete. It fails to explain response format, pagination mechanics, status filter values, or the siteId and confirmProductionWrite parameters, leaving significant gaps for an agent.
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 60%, but the description adds no extra meaning to any parameter. It does not mention page, limit, siteId, status, or confirmProductionWrite, leaving the undocumented parameters (page, limit) without any aid beyond 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?
The description clearly states 'List email campaigns' which is a specific verb and resource. It distinguishes the tool from sibling list tools by resource (campaigns), though it does not explicitly differentiate from other campaign-related tools like thincms_get_campaign. However, 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?
No guidance is provided on when to use this tool versus alternatives such as thincms_get_campaign for a single campaign or thincms_search for broader queries. There are no use-case descriptions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all categories with post counts and hierarchy information.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description should disclose behavioral traits like pagination, sorting, or performance. It only states it lists categories with post counts and hierarchy, omitting important details for an effective list operation.
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?
One sentence that effectively conveys the core purpose. Could include more detail without becoming verbose, but remains efficient and front-loaded.
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?
Lacks output schema, so the description should elaborate on return values beyond 'post counts and hierarchy.' No mention of pagination, filtering, or ordering, making it incomplete for a list 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 100%, so the schema already provides detailed explanations for both parameters (siteId and confirmProductionWrite). The tool description adds no further parameter insights, baseline score 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?
The description clearly states the action (list categories) and includes specific details about the returned data (post counts, hierarchy information), distinguishing it from other list tools like thincms_list_posts.
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?
No guidance on when to use this tool versus alternatives (e.g., listing categories vs. listing posts). No mention of prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all items in a collection, ordered by sortOrder.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| enabled | No | Filter by enabled status | |
| collectionId | Yes | Collection ID | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It states items are ordered by sortOrder, but doesn't clarify if the operation is read-only, requires specific permissions, or has any side effects. It also fails to mention pagination or response format. The description is too sparse for a list operation with 4 parameters.
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 a single sentence that immediately communicates the action, resource, and ordering. Every word is functional; there is no redundancy or unnecessary detail. It is front-loaded with the core purpose.
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 complexity of 4 parameters and no output schema, the description is too brief. It does not explain what constitutes a collection item, whether results are paginated, how sortOrder is interpreted, or any default filtering. The schema descriptions compensate partially for parameters, but the description lacks essential context for a list 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 100%, so baseline is 3. The description adds no parameter-specific information beyond what the schema already provides. The schema descriptions are detailed (e.g., siteId explains concurrent session usage, confirmProductionWrite explains production write requirement), so the description neither adds nor detracts 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?
The description clearly states the verb 'List' and the resource 'all items in a collection', with the ordering by 'sortOrder'. This distinguishes it from sibling tools like thincms_get_collection (which gets collection metadata) and thincms_create_collection_item (which creates items). The purpose is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives, such as thincms_get_collection or other collection-item tools. While the verb 'list' implies a read operation, there is no mention of prerequisites, exclusions, or comparisons to siblings. Usage is implied but not clarified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all collections for the site. Collections are structured data lists (testimonials, reviews, products, team members) that render via {{collection:slug}} template tag in multiple display modes: cards, carousel, banner, list, compact.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| enabled | No | Filter by enabled status | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden. It correctly implies a read operation but does not explicitly state it is non-destructive or mention pagination, rate limits, or response structure. The presence of confirmProductionWrite in schema for a list tool is confusing and not addressed.
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 a single sentence with clarifying examples, effectively front-loaded with the core purpose. It is concise with minimal waste, though it could benefit from bullet points for readability.
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 description fails to mention what the tool returns (e.g., an array of collection objects) and does not cover important details like pagination, sorting, or default behavior. Given no output schema, this is a significant gap for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no parameter-specific details beyond the schema, but it does provide context about collections that enriches parameter understanding (e.g., what kinds of lists exist). No contradiction or meaningful addition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('collections') and provides examples of what collections contain and how they render, distinguishing it from sibling tools like thincms_get_collection (single item retrieval) and thincms_create_collection (creation).
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 explains that the tool lists all collections and what collections are, but does not explicitly guide when to use it versus alternatives (e.g., thincms_get_collection for a specific collection) or when to filter by enabled status or use siteId override. The context is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all reusable content blocks for the site. Optional enabled filter. Content blocks are HTML fragments insertable via {{block:slug}} template tags in the page frame or page/post content.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| enabled | No | Filter by enabled status | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the full burden. While the description implies a read operation ('List'), it does not explicitly state that the tool is read-only or safe. The presence of the confirmProductionWrite parameter (typically for write operations) creates ambiguity without explanation. The description should clarify that despite this parameter, the tool is non-destructive.
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 two sentences, front-loaded with the main action, and every sentence serves a purpose. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters (including the ambiguous confirmProductionWrite), no output schema, and no annotations, the description is insufficient. It lacks context on return format, pagination, and the read-or-write nature of the call. The minimal description leaves gaps for an agent to safely invoke the 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 100%, so the baseline is 3. The description adds value by explaining what content blocks are and that an optional enabled filter exists, but it does not go beyond the schema for parameter details like siteId or confirmProductionWrite. The added context is marginal for parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all reusable content blocks for the site, distinguishes from siblings like thincms_get_content_block (single block) and thincms_create_content_block, and explains the nature of content blocks as HTML fragments used via template tags. The verb 'list' is specific and the resource 'content blocks' 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 provides no guidance on when to use this tool versus alternatives (e.g., thincms_get_content_block for a single block), nor does it mention when not to use it. It implicitly advises it returns all blocks, but fails to set context for selection among similar list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List courses with optional filters. Returns courses with module/enrollment counts.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (default: 1) | |
| limit | No | Items per page (default: 20) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| status | No | Filter by status | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions returning counts, which is useful, but does not explicitly confirm the operation is read-only or describe any side effects or permission requirements. This is acceptable but could be more transparent.
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 two concise sentences, with no wasted words. It is front-loaded with the core purpose and provides a useful output note.
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 list tool with 5 parameters and no output schema, the description is largely complete. It mentions the return value (counts), but could be improved by noting that pagination is available (though the schema covers that). Overall, it adequately covers the tool's function.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the baseline is 3. The description mentions 'optional filters' but adds no additional meaning beyond what the schema already provides for parameters like page, limit, siteId, status, and confirmProductionWrite.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List courses'), the resource, and the output ('with module/enrollment counts'). It effectively distinguishes from CRUD siblings like thincms_create_course and thincms_update_course.
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 this is for listing courses with optional filters, but it does not explicitly state when to use this tool versus alternatives or provide any context about when not to use it. There is no mention of alternatives among the many sibling list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List course enrollments with optional filters. Returns enrollments with user and course details.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (default: 1) | |
| limit | No | Items per page (default: 50) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| status | No | Filter by enrollment status | |
| courseId | No | Filter by course ID | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It only states it lists enrollments and returns details, but fails to mention read-only nature, pagination behavior, or other constraints. Minimal disclosure beyond the 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 sentences, no filler, front-loaded with purpose. Every word 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?
Given no output schema and 6 parameters, the description is brief but covers the essential purpose. However, it lacks details on pagination defaults or response structure, which would aid completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents parameters. The description adds no new meaning beyond stating 'optional filters', which is generic. 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 clearly states the verb 'List', the resource 'course enrollments', and mentions optional filters and returned details (user and course). This distinguishes it from sibling tools like thincms_create_enrollment (create) or thincms_list_courses (list courses).
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?
No explicit guidance on when to use this tool versus alternatives such as thincms_list_courses or thincms_create_enrollment. The purpose is implied but not reinforced with when-not or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all forms and surveys with submission counts.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It implies a read operation ('list') but does not disclose idempotency, permission requirements, or whether it counts submissions in real-time. Minimal behavioral 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?
Single sentence, no waste. Concise but lacks structured formatting (e.g., bullet points for different output details). Efficient but could be more 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?
No output schema exists, yet description only says 'with submission counts'—vague. Missing details on pagination, filtering, result structure, or whether siteId override applies to form listing. Incomplete for a list tool with two optional parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both parameters have thorough descriptions in the schema. The tool description adds no new parameter information beyond 'with submission counts', which hints at output but not inputs. 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?
Description uses a specific verb ('List') and resource ('forms and surveys') with added detail ('with submission counts'), clearly distinguishing it from sibling tools like thincms_get_form (single form) and thincms_list_submissions (submissions, not forms).
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?
No guidance on when to use this tool versus alternatives (e.g., thincms_get_form for a specific form, thincms_list_submissions for submissions of a form). Lacks context on prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all mailing lists from the connected email platform.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Integration ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must disclose behaviors. It only states a read operation, but fails to mention that the call requires an integration ID or that it may require site overrides or production write acknowledgments. The behavioral details are insufficient.
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 a single sentence with no redundant words, perfectly concise and front-loaded. Every word 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?
With no output schema, no annotations, and 3 parameters (including a required id and optional siteId/confirmProductionWrite), the description is too minimal. It does not guide the agent on how to use the parameters or what to expect in return. Incomplete for effective tool usage.
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 parameters. The description adds no additional meaning beyond 'mailing lists from the connected email platform', which does not explain the required 'id' parameter or optional parameters. Meets baseline with no extra 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?
The description clearly states the tool lists all mailing lists from the connected email platform, with specific verb and resource. It distinguishes itself from other list tools by focusing on mailing lists, and 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?
No explicit when-to-use or when-not-to-use guidance is provided. The description implies usage for listing mailing lists, but does not compare with alternatives like thincms_list_integration_tags or thincms_list_subscribers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all tags from the connected email platform.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Integration ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must bear full responsibility for behavioral disclosure. The description is a single line that does not mention whether the operation is read-only, what happens if the integration is missing, or if pagination is involved. The presence of 'confirmProductionWrite' in the schema (which suggests a mutation safeguard) is unexplained and contradicts the listing intent.
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 a single, clear sentence that front-loads the action. However, it may be too brief, lacking necessary details for completeness. Still, it earns its place without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description should explain what the tool returns (e.g., list of tag objects). It does not. Additionally, given the confusing inclusion of 'confirmProductionWrite' for a list operation, the description fails to address that oddity. Overall, the description is incomplete for effective agent 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?
The input schema has 100% coverage; each parameter already has a description. The tool description adds no additional semantic information beyond the schema. Per guidelines, 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 clearly states the action ('list') and the resource ('tags from the connected email platform'). It distinguishes from sibling 'thincms_list_tags' by specifying the source, making it easy for an agent to select the correct tool.
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?
No guidance is provided on when to use this tool vs alternatives. It does not mention prerequisites (e.g., an integration must exist), nor does it clarify that sibling 'thincms_list_tags' lists CMS tags instead. An agent would lack context for proper selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all lead magnets for the site.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must disclose behavior. It only says 'list all' without detailing read-only nature, pagination, site context, or potential performance implications. Minimal 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?
The description is a single sentence with no verbosity, but it is too minimal to earn its place. It lacks context that would justify its brevity for a tool with no 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?
The description is incomplete for a tool with no output schema and no annotations. It does not explain what lead magnets are, how the list is returned, or that the site can be overridden via siteId, which is critical context.
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%, baseline is 3. The description adds no parameter meaning beyond the schema; it does not explain siteId or confirmProductionWrite, which are already well-documented in 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?
The description clearly states 'list all lead magnets for the site' with a specific verb and resource. It distinguishes this tool from siblings like thincms_get_lead_magnet (single) and thincms_create_lead_magnet.
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?
No guidance is provided on when to use this tool versus alternatives. There is no mention of contexts, exclusions, or comparisons to other list tools or sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List uploaded media files with pagination. Returns file metadata including paths, dimensions, and alt text.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (default: 1) | |
| limit | No | Items per page (default: 30) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| visibility | No | Filter by visibility | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It indicates a read operation (list) with pagination, but does not explicitly state whether it is read-only, safe, or has side effects. The presence of the 'confirmProductionWrite' parameter is incongruent with a read operation and is not explained, which could confuse an agent.
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 two sentences long with no superfluous text. It is front-loaded with the core action and key features, making it efficient for an agent to process.
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 lack of an output schema, the description helpfully lists return fields (paths, dimensions, alt text). However, it omits mention of filtering capabilities (visibility parameter) and does not address the incongruous 'confirmProductionWrite' parameter, which is unusual for a list tool and could use clarification.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter already has a description. The description adds minimal value beyond what is in the schema; it mentions pagination (mapping to page/limit) and return fields, but does not elaborate on parameter details like filtering by visibility or the siteId override semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'uploaded media files', and key features 'pagination' and 'returns file metadata including paths, dimensions, and alt text'. This distinguishes it from sibling tools like thincms_get_media (single item) and thincms_upload_media (write operation).
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 for listing media but lacks explicit guidance on when to use this tool versus alternatives such as thincms_get_media for a single file. No when-not or alternative tool mentions are provided, leaving it to the agent to infer from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List static pages with optional status filter and pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (default: 1) | |
| limit | No | Items per page (default: 50) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| status | No | Filter by status | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; the description does not explicitly state side effects, but the tool name implies a read operation. It does not add caution about permissions or destructive potential, but is not misleading.
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?
One short sentence that is front-loaded with the core purpose, containing no unnecessary words.
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?
Does not mention siteId or confirmProductionWrite parameters, nor describe the return format or error handling. For a tool with 5 parameters and no output schema, more completeness is needed.
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 description mentions 'optional status filter and pagination', which adds slight context beyond the schema's parameter names, but does not detail siteId or confirmProductionWrite. With 100% schema coverage, baseline is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and resource 'static pages', and specifies optional filters (status and pagination), distinguishing it from other page operations like get, create, update, delete.
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?
No guidance on when to use this tool vs alternatives such as thincms_get_page for a single page or thincms_search for broader search. The description lacks usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all popups/CTAs for the site with their linked form names.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility. It implies a read-only operation by stating 'List all,' but does not explicitly confirm no side effects, authentication needs, or rate limits. Minimal behavioral 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 a single concise sentence that front-loads the purpose. Every word contributes value; no wasted content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no required parameters and no output schema, the description covers the key information (what is listed and that linked form names are included). It could mention scope (active site) but is sufficient for the tool's complexity.
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 schema already explains both parameters. The description adds no additional meaning about parameters, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and resource 'popups/CTAs' with the added detail of 'with their linked form names,' making the tool's purpose clear. It distinguishes from sibling thincms_get_popup by indicating it lists all popups.
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?
No guidance is provided on when to use this tool vs alternatives (e.g., thincms_get_popup for a single popup). There is no mention of when-not to use it or any context about prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List blog posts with optional filters. Returns posts without content by default (use includeContent=true for full HTML). Supports pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Filter by tag name or slug | |
| page | No | Page number (default: 1) | |
| limit | No | Items per page (default: 20) | |
| series | No | Filter by series name | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| status | No | Filter by status | |
| authorId | No | Filter by author ID | |
| category | No | Filter by category slug | |
| featured | No | Filter featured posts only | |
| publishedTo | No | ISO date: posts published before this date | |
| publishedFrom | No | ISO date: posts published after this date | |
| includeContent | No | Include full HTML content in results (default: false) | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description reveals key behaviors: default content exclusion, pagination support, optional filters. Doesn't disclose rate limits or ordering, but sufficient for a read-only list operation.
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 well-structured sentences. Front-loaded with purpose, then key options. No wasted words.
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 no output schema and 13 parameters, description provides enough context for an agent to understand the tool's purpose and key behaviors. Could mention response format but not required for a list operation.
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 3. Description adds marginal value beyond schema descriptions (e.g., default for includeContent). No major additional semantics.
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?
Clear verb+resource: 'List blog posts'. Distinguishes from siblings like get_post (single) and create/update by specifying optional filters, default content exclusion, and pagination.
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 clear context: use includeContent for full HTML, supports pagination. Does not explicitly state when not to use vs alternatives like get_post, but given the list nature, it's adequate guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all URL redirects. Optionally filter by enabled status.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| enabled | No | Filter by enabled status | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It omits behavioral details like return format, pagination, read-only nature, or permission requirements. The phrase 'List all' suggests no pagination, but this is not confirmed.
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 very concise at two sentences with no waste. However, it could benefit from a bit more context (e.g., mentioning related tools) without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no description of return structure or pagination, the description is incomplete for a list tool. It lacks information on what fields are returned, limits, or error handling, which is needed for effective 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 description coverage is 100% with detailed parameter descriptions (especially siteId and confirmProductionWrite). The tool description itself does not mention parameters, but the schema already covers semantics sufficiently, leading to a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'all URL redirects', with an optional filter. It distinguishes from sibling tools like thincms_get_redirect (single) and thincms_create_redirect (create) by implying a bulk listing operation.
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?
No explicit guidance on when to use this tool versus alternatives such as thincms_get_redirect for a single redirect or thincms_search for more targeted queries. The description only states what it does without any usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Google reviews ingested for the active site (Reviews Module v1). Filterable by post status, rating, sentiment, hold reason, and drift flag. Reviews are pulled from Outscraper on a daily cron schedule; sentiment is run via the configured AI provider. Use postStatus=posted to see what's currently on the public widget.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (default 1). | |
| limit | No | Items per page (default 50, max 200). | |
| rating | No | Filter by rating (1-5). | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| provider | No | Filter by which provider ingested the review. | |
| driftFlag | No | Filter by drift state. 'edited' = changed on Google since capture; 'missing' = no longer returned by Google. | |
| holdReason | No | Filter by why a review is held back from the widget. | |
| postStatus | No | Filter by published-to-widget state. | |
| sentimentLabel | No | Filter by computed sentiment label. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that reviews are ingested daily from Outscraper and sentiment is computed via AI provider. It also explains the confirmProductionWrite parameter's role. However, it does not mention rate limits, authentication requirements, or whether the list operation is read-only. Overall, it provides useful behavioral context beyond the 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?
The description is four sentences, front-loaded with the core purpose, followed by filtering capabilities and data source context. Every sentence adds value without redundancy. It is concise and well-structured.
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 has 10 parameters and no output schema, the description covers the main purpose, filtering dimensions, data provenance, and a usage hint. It lacks details on the response format (e.g., list of review objects) and any pagination behavior beyond what's in the schema. Still, it provides sufficient context for an AI agent to understand when and how to use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description lists the filterable fields (post status, rating, sentiment, hold reason, drift flag) which groups parameters, but adds little semantic detail beyond what the schema already provides. The usage hint for postStatus is a small addition. Overall, minimal extra 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?
The description clearly states 'List Google reviews ingested for the active site (Reviews Module v1).' This specifies the verb 'list' and the resource 'Google reviews', and distinguishes it from other list tools by narrowing to reviews and the active site 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?
The description provides a concrete usage hint: 'Use postStatus=posted to see what's currently on the public widget.' It also explains the data source (Outscraper, daily cron) but does not explicitly state when to use alternatives like thincms_get_review or other list tools. The guidance is helpful but could be more comprehensive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all script injections (analytics, chat widgets, tracking pixels, etc.).
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description bears full responsibility for behavioral disclosure. It merely states the action without mentioning side effects, authentication needs, rate limits, or consequences of use.
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 a single concise sentence (~12 words) that front-loads the purpose with no extraneous 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?
As a simple list operation with no output schema, the description is adequate but lacks details on return format, pagination, or what fields the response contains. It is minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameters (siteId, confirmProductionWrite) are already well-described in the schema. The description adds no additional meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('script injections'), with examples like analytics and chat widgets. However, it does not explicitly differentiate from sibling tools like create_script or update_script, though the action difference is implied.
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 provides no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List environment variable secrets. Returns key names and descriptions only — values are never returned for security.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully bears the burden of behavioral disclosure. It explicitly states that values are never returned for security, providing important safety and behavioral 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 a single, concise sentence that front-loads the primary action. Every word adds value; no waste.
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 description explains the return content (key names and descriptions) but lacks details on the structure (e.g., array of objects). For a simple list tool, this is mostly adequate. With no output schema, a bit more precision would be helpful.
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 both parameters are well-described in the schema. The description does not add additional semantic value beyond the schema, so baseline score of 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 clearly states the tool lists environment variable secrets and specifies that it returns only key names and descriptions, not values, distinguishing it from other tools.
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 use for viewing secret metadata but does not explicitly state when to use this tool versus alternatives like thincms_create_secret or thincms_get_secret (if exists). No guidance on exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List email sequences (drip campaigns) with their steps.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It only states 'List email sequences with their steps,' which implies a read operation but does not confirm idempotency, side effects, authorization needs, or any limitations (e.g., pagination, rate limits). Critical safety details are absent.
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 a single, well-structured sentence of 8 words, conveying the core purpose without redundancy. It is front-loaded and efficient, earning top marks for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema and no annotations, the description provides only minimal context for a list tool. It does not mention return format, sorting, filtering, or pagination. While adequate for a simple tool, it leaves gaps that could confuse an agent, especially among many sibling list 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?
The input schema already has 100% description coverage, providing detailed explanations for both parameters (siteId and confirmProductionWrite). The tool description adds no additional parameter meaning, but since schema coverage is high, a baseline score of 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 clearly states the tool lists email sequences (drip campaigns) and includes their steps. It effectively conveys the action and resource, distinguishing it from related tools like thincms_get_sequence. However, it does not explicitly specify scope (e.g., whether it lists all sequences or supports filtering), which prevents a higher score.
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?
No guidance is provided on when to use this tool versus alternatives such as thincms_get_sequence or thincms_list_campaigns. The description offers no context about appropriate scenarios, prerequisites, or exclusions, making it hard for an agent to decide when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all configured ThinCMS sites with preview URLs and status (preview/live). Shows which site is currently active.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It states the output but does not mention safety, authorization, or side effects (though likely read-only). The description adds minimal value beyond obvious functionality.
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 sentence that is front-loaded with the action and resource. No unnecessary words; every part is informative.
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 has no parameters and no output schema, the description sufficiently covers what the tool does and what it returns. It is complete for a simple list operation.
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?
There are no parameters (schema coverage 100%), so the description need not explain any. Baseline for 0 parameters is 4, and the description does not add parameter info since none exist.
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 uses a specific verb 'List' and clearly identifies the resource 'all configured ThinCMS sites' with additional details on what is returned (preview URLs, status, active site). This distinguishes it from siblings like thincms_switch_site.
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?
No guidance on when to use this tool versus alternatives (e.g., before switching sites) or when not to use it. The description lacks context for appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all snapshots taken in the current MCP wrapper session. Useful for finding the right snapshotId to restore, or auditing what test writes have been made.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the scope ('current MCP wrapper session') but does not explicitly state that the tool is read-only or has no side effects. This is adequate for a list operation but could be more transparent.
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 two sentences: the first states what the tool does, the second adds use cases. No redundant information, every sentence 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?
Given no annotations, no output schema, and 0 parameters, the description adequately explains the tool's purpose and scope. It might benefit from mentioning output format or pagination, but it is sufficiently complete for a simple listing 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?
The input schema has 0 parameters and 100% schema coverage, so the baseline is 4. The description adds no parameter info, which is fine since there are none to document.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists all snapshots taken in the current MCP wrapper session. It distinguishes itself from sibling tools like thincms_restore_snapshot and thincms_snapshot by specifying the listing action and scope.
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 provides context for when to use it (finding snapshotId for restore, auditing test writes) but does not explicitly state when not to use it or compare to alternatives. The context is clear enough for a simple listing tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List form submissions with pagination. Returns submission data (field values) and timestamps.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (default: 1) | |
| limit | No | Items per page (default: 20) | |
| formId | Yes | Form ID (required) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It implies a safe read operation with 'List' but doesn't confirm read-only, auth needs, or pagination behavior details. Adequate but could be more explicit.
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 with no wasted words. Front-loaded with main action and pagination, then return details. Efficient and clear.
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 5 straightforward parameters and no output schema, the description covers core functionality (listing, pagination, return content). Could mention metadata like total count, but sufficient for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by stating the return format (field values and timestamps), which is not in schema. This helps the agent understand output beyond parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists form submissions with pagination, and specifies it returns submission data and timestamps. This distinguishes it from siblings like thincms_export_submissions_csv and thincms_delete_submission.
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?
No explicit guidance on when to use this tool versus alternatives (e.g., export vs list). It implicitly suggests usage for paginated listing but lacks when-not or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List subscribers/members with optional search and pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (default: 1) | |
| limit | No | Items per page (default: 20) | |
| search | No | Search by email or name | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description claims a read-only 'list' operation, yet the input schema includes 'confirmProductionWrite' which typically indicates a write operation. This inconsistency is not addressed. No annotations are provided, so the description fails to disclose potential side effects. Without annotations, the description carries the full burden of transparency.
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?
Single sentence that is efficiently front-loaded, but could be slightly more informative without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and no description of return format. With 5 parameters and a potentially misleading behavioral implication, the description is insufficiently complete for an agent to use reliably.
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 description adds minimal value beyond what the schema already provides. It mentions 'optional search and pagination' but does not elaborate on parameter usage or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists subscribers/members, which matches the tool name. It mentions optional search and pagination, but does not differentiate from other list tools like thincms_list_posts, thincms_list_sites, etc.
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?
No guidance on when to use this tool versus other list tools or alternative approaches. No exclusions or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all tags with post counts.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies it is a read-only list operation (safe), but without annotations, it does not disclose potential side effects, authentication requirements, or pagination behavior. The brevity leaves some transparency gaps.
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 a single sentence with no redundancy. Every word adds value, perfectly front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While parameter descriptions are thorough, the tool description lacks details on return format, pagination, or any edge cases. Given the absence of an output schema, this is a gap, though the simplicity of the tool mitigates 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 coverage is 100% with detailed parameter descriptions. The tool description adds no additional meaning beyond the schema, so baseline score of 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?
The description clearly states the verb 'List' and the resource 'tags' with an additional detail 'with post counts'. This distinguishes it from sibling list tools like thincms_list_categories and thincms_list_authors.
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?
No guidance is provided on when to use this tool versus alternatives like thincms_get_tag for a specific tag, or when to consider site overrides. The description lacks any context for selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all data keys visible to the caller — merges per-user (when subscriberId is supplied) with tool-global. Per-user values shadow global at the same key. Returns each key with its value, scope ('user' or 'global'), and updatedAt.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Tool ID or slug | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| subscriberId | No | End-user Subscriber ID to view merged with tool-global | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses merging of per-user and global data with shadowing, return fields (key, value, scope, updatedAt). No annotations provided, so description carries full burden. Missing potential pagination or rate limits, but read-only nature is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no waste. Front-loaded with purpose and immediately explains key behavior.
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?
Explains return structure (key, value, scope, updatedAt) despite no output schema. Lacks pagination info but complete for a list tool with clear merging.
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%, baseline 3. Description adds context for subscriberId (merging behavior) beyond schema. Other parameters (id, siteId, confirmProductionWrite) are adequately described in 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?
Clearly states 'List all data keys visible to the caller' with specific verb and resource. Distinguishes from sibling tools by describing merging behavior of per-user and global 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?
Explains when to use subscriberId ('when subscriberId is supplied') and that per-user values shadow global. No explicit when-not-to-use statement, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List end-user Subscribers who have interacted with a Tool (have data rows or AI usage on it), sorted by most-recent activity. Returns id, email, name, emailVerified, lastLoginAt, and lastActiveOnTool.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Tool ID or slug | |
| page | No | Page number (default: 1) | |
| limit | No | Items per page (default: 50) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses sorting by recent activity and return fields, but does not mention pagination behavior, rate limits, auth requirements, or side effects. Some behavioral context is given, but not comprehensive.
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 fluff. Purpose is front-loaded, and return fields are listed efficiently. Every clause adds value.
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 list tool with 5 parameters and rich schema, the description is nearly complete. It provides purpose, sorting, and return fields. However, it omits pagination metadata (e.g., whether total count is returned) and ordering direction (most-recent implies descending). Still, sufficient for typical 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 100%, so baseline is 3. Description does not add extra parameter information beyond what the schema already provides (e.g., id, page, limit). No additional meaning is contributed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it lists end-user subscribers who have interacted with a specific tool, sorted by most-recent activity. It specifies the fields returned (id, email, etc.), which distinguishes it from generic subscriber list tools like thincms_list_subscribers.
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?
Description implies when to use (when needing subscribers with tool interaction) but does not explicitly state when not to use or provide comparisons to sibling tools like thincms_list_subscribers or thincms_list_tool_data. Usage is implied but not fully guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List publishable Tools (mini-apps) with optional status/enabled filters and pagination. Tools render at /tools/:slug and can be authenticated (Google or password), store per-user JSON data, and call AI via /ai/chat and /ai/complete.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (default: 1) | |
| limit | No | Items per page (default: 50) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| status | No | Filter by status | |
| enabled | No | Filter to enabled tools only when true | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It correctly implies a read-only operation by using 'List', which is standard for query tools. No hidden side effects are mentioned, but none are expected for a listing tool. The extra context about tool capabilities adds useful behavioral insight.
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 consists of two concise sentences. The first sentence states the core purpose and features; the second provides useful domain context about tools. Every sentence is earned with no wasted words, making it easily 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?
While the description covers filtering and pagination, it omits important context such as the site-aware behavior (siteId parameter, confirmProductionWrite) and does not describe the return format or fields. Given the absence of an output schema, these gaps reduce completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 6 parameters with full descriptions (100% coverage), so the baseline is 3. The description mentions 'optional status/enabled filters and pagination', which aligns with the schema but adds no new semantic value beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'List publishable Tools (mini-apps)', which immediately identifies the verb and resource. It also specifies optional filters (status, enabled) and pagination, distinguishing it from other list tools like thincms_list_posts or thincms_list_sites.
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 does not provide explicit guidance on when to use this tool versus alternatives (e.g., thincms_get_tool for a single tool). Usage is implied by the name and purpose, but no when-not-to or alternative suggestions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List workbooks across the site, optionally filtered by course or module. Each result includes module info and a response count.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| courseId | No | Filter by course ID | |
| moduleId | No | Filter by module ID | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states it lists workbooks with module info and response count, implying a read operation. However, no annotations are provided, and the description does not explicitly confirm safety or mention any side effects. It is adequate but not thorough.
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 a single efficient sentence. It is front-loaded with the core action and resource. Could be improved by adding context about when to use filters, but no wasted words.
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 good schema coverage, the description omits key parameter context (siteId, confirmProductionWrite) and does not fully describe output beyond 'module info and response count.' Given complexity (4 params, no output schema), more detail is needed for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for all 4 parameters. The description adds minimal value beyond schema: it hints at filtering by course/module but does not elaborate on siteId or confirmProductionWrite, which are important for multi-tenant contexts.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list) and resource (workbooks) with optional filters. It distinguishes from sibling tools by focusing on workbooks, which is unique among many list tools.
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 mentions optional filters but does not explain when to use this tool over alternatives (e.g., thincms_get_workbook for a single workbook). No when-not or explicit context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace a named section of the stylesheet between comment markers. The stylesheet must contain /* START: / and / END: */ markers. Only the content between these markers is replaced.
IMPORTANT — what to send: pass ONLY the body to insert between the markers, not a full stylesheet. If your input contains its own START: and END: markers matching the same section name, the API will auto-extract the body for you. If it contains markers for a DIFFERENT section, the call is rejected to prevent silent doubling. Use dryRun=true on large patches to verify the size delta before committing.
| Name | Required | Description | Default |
|---|---|---|---|
| css | No | Replacement CSS for the section. Send only the body content (not a full stylesheet). | |
| dryRun | No | When true, return the size delta the change would produce without writing. Strongly recommended before any large patch. | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| cssFile | No | Local file path containing replacement CSS. The file may contain matching START:/END: markers for the named section — if present, the body between them is auto-extracted. If the file contains markers for a different section, the call is rejected. | |
| section | Yes | Section name matching comment markers in the stylesheet (e.g., 'hero' matches /* START:hero */ ... /* END:hero */) | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It explains key behaviors: replacement only between markers, auto-extraction with matching markers, rejection for different markers, and dry run behavior. It also hints at production write protection via confirmProductionWrite. Missing details about required permissions or side effects on the rest of the stylesheet, but these are not critical.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: first sentence establishes purpose, then explains markers, critical input rules in caps, and practical recommendation. It is concise at 5 sentences with zero wasted words and front-loaded with the core action.
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 (6 parameters, no output schema), the description covers essential aspects: marker-based replacement, input requirements, dry run, and site targeting. It does not describe the return value or how to identify existing markers, but these are minor omissions. Overall, it equips an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant value beyond schema descriptions. It clarifies that 'css' should be only body content, explains auto-extraction for 'cssFile', details marker format for 'section', recommends 'dryRun' for large patches, and describes 'siteId' as a concurrent-session pattern. This rich context far exceeds baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Replace a named section of the stylesheet between comment markers.' It specifies the verb 'replace' and the resource 'named section of the stylesheet,' with the comment marker mechanism providing precise scope. This distinguishes it from general CSS modification tools like thincms_append_css, which appends rather than replaces.
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 provides explicit guidance on when to use the tool: use dryRun for large patches, avoid sending full stylesheets, and understand marker auto-extraction. It also warns about rejection for mismatched sections. However, it does not compare this tool to alternatives like thincms_append_css, leaving the agent to infer when to use each.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pause a published sequence automation.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Sequence ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a mutation (pause) but does not disclose permissions, idempotency, or side effects. With no annotations present, the description carries the full burden, and it is insufficient.
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 a single, clear sentence with no redundancy. However, it is slightly too brief and could benefit from a bit more context without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters, no output schema, and no annotations, the description is incomplete. It does not explain what happens after pausing (e.g., resumed later, status change) or any return value.
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 schema already documents each parameter. The description adds no additional meaning beyond the parameter descriptions in 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?
The description clearly states the action ('Pause') and the specific resource ('a published sequence automation'), distinguishing it from siblings like thincms_publish_sequence (publish) and thincms_delete_sequence (delete). The mention of 'published' adds necessary 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?
No guidance on when to use this tool versus alternatives (e.g., when to pause vs delete or update a sequence). No prerequisites or conditions for use are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a review as posted to the public reviews widget. Sets postStatus='posted' and clears any holdReason. Subject to the production-write guard if the site is in THINCMS_PRODUCTION_SITE_IDS — pass confirmProductionWrite=true to acknowledge.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Review ID. | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden for behavioral transparency. It discloses the effect on postStatus and holdReason, and the production guard requirement. However, it does not discuss reversibility, authorization needs, or any side effects, leaving some gaps for an agent to infer.
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 extremely concise at two sentences. The first sentence communicates the primary purpose and effect, and the second adds critical behavioral context (production guard). No unnecessary words 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?
For a mutation tool with no output schema, the description adequately covers the action and key constraint (production guard). It does not describe return values or confirmation, but the tool's purpose is straightforward. The context is nearly complete given the low complexity.
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 parameters are well-described in the schema. The description adds meaningful context for confirmProductionWrite by explaining the production-write guard and acknowledgment pattern. It does not add information for the id or siteId parameters, but the schema already covers them adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('mark a review as posted') and specifies the resource ('public reviews widget'). It also describes the database effect (sets postStatus, clears holdReason). This distinctly helps an agent understand what the tool does and differentiates it from sibling tools like thincms_unpublish_review.
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 mentions the production-write guard and the need for confirmProductionWrite, but does not explicitly state when to use this tool vs alternatives like thincms_unpublish_review or thincms_clear_review_drift. Usage context is implied but not fully clarified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Publish a sequence as an automation in the email platform.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Sequence ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fails to disclose key behaviors: what publishing entails (e.g., activating emails), reversibility, side effects, or required setup. The description is minimal and does not fulfill the transparency burden.
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 a single sentence with no fluff, but it lacks essential details. It is concise but incomplete, which reduces its helpfulness.
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 complexity of publishing a sequence as an automation and the absence of an output schema or annotations, the description is severely lacking. It does not explain return values, prerequisites, effects, or post-conditions.
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 schema has 100% coverage for all 3 parameters. The description adds no extra meaning beyond the parameter descriptions already in the schema. 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 clearly states the action (publish) and resource (sequence) with target context (automation in email platform). It distinguishes from sibling tools like thincms_create_sequence or thincms_pause_sequence, though it could be more precise about the outcome.
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?
No guidance on when to use this tool versus alternatives (e.g., thincms_create_sequence for creation, thincms_pause_sequence for pausing). No prerequisites or conditions stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-run sentiment analysis for a single review (id) or all reviews on the site (all=true). Useful after switching the AI provider in Settings. Does NOT change postStatus — only sentiment fields. Admin-only.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Review ID. Omit when using all=true. | |
| all | No | Re-analyse every review on the site (capped at 500). | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It states the tool does NOT change postStatus and only updates sentiment fields, which is key behavioral information. It also notes admin-only. However, it does not explicitly state that it performs a write operation or disclose potential side effects like rate limits or conflicts if both 'id' and 'all' are provided.
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 three concise sentences. The first sentence states the purpose, the second provides a use case, and the third clarifies side effects and access. No unnecessary words, and front-loaded with the core action.
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 no output schema, the description covers essential behavioral aspects and parameters. It lacks explanation of return values or errors, but the tool is straightforward. Overall, it is fairly complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description does not add new parameter-specific meaning beyond what the schema already provides. The baseline of 3 is appropriate since the schema adequately documents all parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it re-runs sentiment analysis for a single review or all reviews, with specific verb 're-run' and resource 'review sentiment'. It distinguishes from siblings like thincms_publish_review, thincms_sync_reviews, etc., by focusing solely on sentiment re-analysis.
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 says 'Useful after switching the AI provider in Settings', providing a specific context. It also notes 'Admin-only' for access. However, it does not explicitly mention when not to use it or alternative tools for similar tasks (e.g., thincms_sync_reviews).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bulk reorder items in a collection. Pass an array of { id, sortOrder } pairs.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Array of { id, sortOrder } pairs | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| collectionId | Yes | Collection ID | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must convey behavioral traits. It states a 'reorder' operation (write) but does not mention side effects, permission requirements, idempotency, error handling, or whether sortOrder is relative or absolute. The description is too sparse for a mutation 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?
The description is very short (two sentences) and front-loaded with the main action. It could be slightly more concise by combining sentences, but overall it is efficient and to the point.
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 no output schema, the description should at least mention what the tool returns or confirm success. It also omits important context like the required collectionId parameter in the description, potential constraints on sortOrder values, and whether the operation is atomic. The tool is underspecified for a bulk operation.
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%; each parameter is documented. The description repeats the items format ('array of { id, sortOrder } pairs') but adds no further semantic meaning beyond the schema (e.g., range, uniqueness, or ordering behavior of sortOrder). 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 clearly states 'Bulk reorder items in a collection' with a specific verb and resource. It is not a tautology. However, it does not explicitly differentiate from sibling tools like thincms_reorder_modules or thincms_reorder_module_items, though the name itself is specific.
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 use for bulk reorder of collection items but lacks guidance on when not to use it or alternatives (e.g., single item update via thincms_update_collection_item). No context about prerequisites or conditions is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reorder lessons, quizzes, and workbooks within a module. All three types share a single sort order space — pass all items in the desired order with their type.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Array of items in desired order | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| moduleId | Yes | Module ID (required) | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that the tool expects all items to be passed in desired order and that types share a single order space, which is helpful. However, it omits important behavioral traits such as idempotency, what happens if items are omitted, or any side effects like confirmation requirements (though confirmProductionWrite parameter hints at write operations).
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 consists of two short sentences with no redundancy. The first sentence immediately states the goal, and the second adds a critical constraint. It is perfectly sized for quick comprehension.
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 that the tool has no output schema and four parameters with full schema descriptions, the description adequately covers the core behavior. It explains the shared order and the requirement to pass all items. While it could be more explicit about validation and missing items, it is sufficient for a straightforward reorder operation.
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 baseline is 3. The description adds meaningful context beyond the schema by clarifying that the three item types coexist in a single sort order space and that the items array should contain all items. This helps the agent understand the parameter's purpose more deeply.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly uses the verb 'Reorder' and specifies the resource 'lessons, quizzes, and workbooks within a module', which is distinct from sibling reordering tools that target different scopes (e.g., modules or collection items). It also explains the shared sort order space, adding precision.
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 implicitly defines its use case by specifying 'within a module' and noting that all three item types share a single sort order. While it does not explicitly contrast with sibling tools, the context is clear enough to guide appropriate selection. However, it could explicitly state when not to use it or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reorder modules within a course. Pass all module IDs in the desired order.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| courseId | Yes | Course ID (required) | |
| moduleIds | Yes | Array of module IDs in desired order | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden but only states that it reorders modules and requires all module IDs. It does not disclose side effects, permissions, idempotency, or return behavior beyond the reorder action.
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 a single, clear sentence with no unnecessary words. It is front-loaded and immediately communicates the core functionality.
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 reorder tool with no output schema and no annotations, the description is adequate but lacks behavioral details such as whether the operation is destructive, the expected return value, or how errors are reported. It covers the basic purpose but is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds only a slight emphasis on 'pass all module IDs' but does not provide additional meaning beyond what the schema already conveys.
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 explicitly states the verb 'Reorder' and the resource 'modules within a course', and it clearly distinguishes from siblings like 'thincms_reorder_module_items' which reorders items inside a module.
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 for reordering modules but provides no explicit guidance on when to use this tool versus alternatives (e.g., thincms_reorder_collection_items for collections), nor does it mention prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reorder steps in a sequence.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| stepIds | Yes | Step IDs in desired order | |
| sequenceId | Yes | Sequence ID | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It does not disclose that it is a write operation (though confirmProductionWrite parameter hints), nor does it explain effects, authorization needs, or error conditions. The description is too minimal.
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 a single sentence, concise and front-loaded. However, it is too minimal and could include more context without being verbose.
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?
No output schema, and the description does not explain return values or how this fits into the workflow (e.g., reordering steps in an email sequence). Lacks information about expected preconditions and 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 coverage is 100%, each parameter has a description. The tool description adds no new meaning beyond the schema, so 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 clearly states the action (reorder) and resource (steps in a sequence). It distinguishes from sibling reorder tools like thincms_reorder_modules by specifying 'steps in a sequence', though it could be more explicit about the context (email sequences).
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?
No guidance on when to use this tool vs alternatives (e.g., thincms_reorder_modules or thincms_reorder_collection_items). No mention of prerequisites such as the sequence existing or steps belonging to the sequence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a previously-captured snapshot back to its original resource. Reverts the resource to the exact bytes captured at snapshot time. Fails if the snapshot has expired (24h) or the resource has been deleted. Use as the cleanup step after any test write.
| Name | Required | Description | Default |
|---|---|---|---|
| snapshotId | Yes | The snapshot ID returned by thincms_snapshot. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully discloses the write action, the fact that it reverts the resource, and failure conditions. It implies it is safe for testing. It could explicitly state that the current state is overwritten, but still strong.
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 front-loaded sentences with no fluff: first states action, second adds detail and failure conditions, third gives usage guidance. Every sentence 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 tool with one parameter and no output schema, the description covers purpose, usage context, and failure cases. It does not specify the return format or permissions, but those are minor gaps given the tool's clarity.
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% (one parameter, snapshotId, described as 'The snapshot ID returned by thincms_snapshot.'). The tool description adds no new semantic information beyond the schema's property description; 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 clearly states the tool's action: writing a snapshot back to its original resource, reverting to exact bytes. It distinguishes from sibling tools like thincms_snapshot (which creates snapshots) and thincms_list_snapshots (which lists 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?
The description explicitly recommends using this tool 'as the cleanup step after any test write,' providing clear context. It also notes failure conditions (expired snapshot, deleted resource). It does not enumerate alternatives, but the purpose is distinct enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full-text search across published posts and pages. Searches titles, excerpts, and content.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Search query (required) | |
| page | No | Page number (default: 1) | |
| type | No | Limit search to posts, pages, or both (default: all) | |
| limit | No | Items per page (default: 20) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions searching only published content and fields searched, but does not disclose reading nature, pagination behavior, or why confirmProductionWrite parameter exists for a search operation.
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?
Extremely concise with two short sentences, front-loaded with the main purpose. Every word adds value.
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?
Lacks details about return format, pagination, filtering options beyond type, and the role of siteId. Given no output schema, more context would be beneficial.
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 all parameters are documented in schema. Description adds no extra meaning beyond schema. Baseline of 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 clearly states it performs full-text search across published posts and pages, searching titles, excerpts, and content. It distinguishes from sibling tools like thincms_list_posts or thincms_get_post, but could be more explicit about the verb (e.g., 'Search').
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?
No guidance on when to use this tool vs alternatives like thincms_list_posts or thincms_get_page. The description implies use for free-text queries, but no explicit when-to-use or when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Push the campaign to the connected mail platform (e.g. ActiveCampaign) and request delivery. If scheduledFor is "immediate" (or the legacy scheduledAt is empty), the platform begins sending right away. If scheduledFor is a future timestamp (or scheduledAt is set), the platform queues it for that time. Returns success when the platform accepts the queue request — actual recipient delivery is asynchronous and reported via thincms_campaign_stats. Optionally pass scheduledFor here to override the stored schedule in the same call. WARNING — the platform locks the schedule at first send. To reschedule a campaign you have already sent, delete it and recreate it; a /send with a changed schedule against an already-queued campaign returns 409.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Campaign ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| scheduledFor | No | Optional override of the stored schedule. "immediate" or an ISO 8601 timestamp at least 60 minutes in the future. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations were provided, so the description carries full burden. It fully discloses behavioral traits: the tool accepts the send request asynchronously, actual delivery is async; scheduling behavior for immediate vs future timestamps; the lock on schedule after first send; the need for confirmProductionWrite for production sites; and the error scenario (409). This is comprehensive.
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 concise but thorough, consisting of two well-structured paragraphs. The first sentence clearly states the purpose. Every sentence adds essential information without redundancy. It is appropriately sized for the complexity.
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 (asynchronous sending, scheduling, production safety), the description covers all critical aspects: what it does, how scheduling works, the lock constraint, the async nature and monitoring via thincms_campaign_stats, and the production write acknowledgment. No output schema exists, but the return behavior is described. This is sufficient for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds significant value beyond the schema: it explains the interaction between scheduledFor and the legacy scheduledAt, the meaning of 'immediate' vs future timestamp, the schedule locking behavior, and the context for confirmProductionWrite. This extra context elevates the score to 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Push the campaign to the connected mail platform and request delivery.' It uses a specific verb ('push') and resource ('campaign'), and distinguishes it from related tools like thincms_create_campaign or thincms_update_campaign by focusing on the sending action.
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 provides explicit guidance on when to use this tool: to send a campaign with optional scheduling. It also explains constraints: the platform locks the schedule after first send, so rescheduling requires delete/recreate, and a /send against an already-queued campaign returns 409. It mentions async delivery and the need to check thincms_campaign_stats. However, it doesn't explicitly tell when not to use it (e.g., if just creating or updating a campaign).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send (or re-send) the email-verification email to a subscriber. Generates a fresh 24-hour verify token, invalidating any prior pending token. Rejected if the subscriber's email is already verified.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Subscriber ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must cover behavioral traits. It does so by disclosing token generation, a 24-hour expiry, invalidation of prior tokens, and rejection when already verified. It does not mention authentication requirements or rate limits, but the core behavioral details are present. No contradiction with annotations (none exist).
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 extremely concise: two sentences that cover the main action and key behavioral constraints. Every sentence adds value with no 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?
The description provides sufficient information for a straightforward single-action tool. It explains the purpose, token behavior, and rejection condition. Missing details like return values are minor given the tool's simplicity and the lack of an output schema.
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 input schema fully describes each parameter. The description adds no additional meaning beyond what is already in the schema. 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 clearly states the action: send or re-send an email-verification email to a subscriber. It specifies the resource (subscriber) and includes key details like token generation and invalidation. Among the many sibling tools, none duplicate this function, so it is well-distinguished.
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 when to use (e.g., to send/re-send a verification email) and explicitly states a condition for not using (rejected if already verified). However, it does not mention alternatives or provide explicit guidance on when not to use it beyond the already-verified case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze a single post or page for SEO signals. Returns word count, heading structure, image count (with missing alt detection), internal/external link counts, meta field lengths, and actionable suggestions.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The post or page ID | |
| type | Yes | Content type to analyze | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations present, so description must disclose behavioral traits. It does not state whether the operation is read-only or has side effects. The output-focused list is helpful but insufficient for an agent to understand safety implications.
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?
Extremely concise: a single sentence that conveys purpose and outputs. No wasted words, front-loaded with the action. Every sentence 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?
Given no output schema, the description lists return values (word count, headings, images, links, meta, suggestions), which is good. However, it omits safety/read-only disclosure and does not mention pagination or behavior for invalid IDs, leaving some gaps for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no extra meaning beyond the schema's parameter definitions; it merely restates the action. No additional context for siteId or confirmProductionWrite.
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?
Clearly states the action (analyze), resource (single post or page), and domain (SEO signals). Lists specific outputs. Does not explicitly differentiate from siblings like thincms_seo_audit, which limits clarity for comparison, but the verb+resource is precise.
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?
No guidance on when to use this tool versus alternatives (e.g., thincms_seo_audit for bulk, thincms_seo_check_links for links). No prerequisites or exclusions stated, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run an SEO audit across all published posts and pages. Reports missing meta descriptions, missing meta titles, title length issues, missing OG images, thin content, missing excerpts, and duplicate titles. Returns a summary with score and a list of issues per item.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read-only audit, but the input schema includes confirmProductionWrite (acknowledging writes to production), creating a contradiction. The description does not explain whether the audit modifies data or has side effects, nor does it mention rate limits or other behavioral traits.
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 concise (two sentences) and front-loads the action. However, the list of checks could be better integrated into a structured format, and the sentence on output is clear.
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 absence of an output schema, the description adequately mentions a summary with score and issues list. However, it fails to clarify the write potential implied by confirmProductionWrite and doesn't differentiate from sibling SEO 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 coverage is 100% with detailed descriptions for both parameters (siteId and confirmProductionWrite). The tool description adds no additional meaning beyond the schema, so a baseline of 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 clearly states the tool runs an SEO audit across all published posts and pages, lists specific checks (missing meta descriptions, titles, OG images, etc.), and notes the output. However, it does not differentiate itself from sibling tools like thincms_seo_analyze or thincms_seo_check_links, which could cause confusion.
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 alternatives (e.g., seo_analyze, check_links). The description only explains what it does, not the optimal use context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan published content for broken links. By default checks internal links only (fast). Set checkExternal=true to also verify external URLs via HEAD requests (slower, limited to 50 URLs). Optionally scope to a single post or page by providing type and id.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Scope to a single post or page ID | |
| type | No | Scope to a single content type | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| checkExternal | No | Also check external URLs (slower). Default: false | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses default scope, performance differences, external URL limit of 50, and optional scoping by type and id. Since no annotations exist, description carries full burden. However, it does not specify output format or whether results are returned in real-time.
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, no redundancy, each provides critical information. Purpose is front-loaded and immediately clear. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should explain what the tool returns (e.g., list of broken links, count). It does not mention return format, which is a gap. Otherwise, covers inputs and switching behaviors well.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the description still adds value by explaining that id and type together scope to a single post/page, and that checkExternal incurs a performance penalty. This enriches the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool scans published content for broken links with a specific verb and resource. It distinguishes from SEO siblings (thincms_seo_audit, thincms_seo_analyze) by focusing on link checking, and provides default vs. external scan behavior.
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?
Clearly explains default internal link checking and when to enable external checking with performance trade-offs and limits. Does not explicitly state when not to use or provide alternatives, but the context and tool name make usage intuitive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set free-text editor notes on a review (internal-only; not shown publicly). Useful for tracking why something was unpublished or what to do about a flagged drift event.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Review ID. | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| editorNotes | Yes | Internal notes (pass empty string to clear). | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It mentions internal-only and not shown publicly, but it does not disclose that the operation overwrites existing notes, nor does it mention error conditions (e.g., review not found). The description is adequate but could be more explicit.
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 extremely concise: two sentences with no unnecessary words. It front-loads the primary action and follows with specific use cases. Every part 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?
Given that the tool has no output schema and the operation is simple (set a string on a review), the description is largely sufficient. It explains the purpose, internal nature, and use cases. However, it could briefly mention that it returns confirmation or success status, but this is not critical.
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 schema already describes each parameter's purpose (e.g., 'editorNotes: Internal notes (pass empty string to clear)'). The description does not add additional meaning beyond what the schema provides, so a baseline score of 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 clearly states the action ('Set free-text editor notes'), the resource ('a review'), and adds context that notes are internal-only. It distinguishes itself from sibling tools like thincms_publish_review or thincms_unpublish_review by specifying it is for editor notes, not status changes.
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 provides concrete use cases ('tracking why something was unpublished or what to do about a flagged drift event'), which helps an agent decide when to use this tool. It does not explicitly state when not to use it or mention alternatives, but the use cases are specific and relevant.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set a password for a subscriber. Admin action for bulk-provisioning end-users of Tools (mini-apps); skips the signup email flow. Password must meet strength rules (8+ chars, upper, lower, digit). Existing sessions for the subscriber are revoked so the new password takes effect everywhere.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Subscriber ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| password | Yes | New password (min 8 chars, must include upper, lower, digit) | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses password strength rules, session revocation, and email skipping. Without annotations, this adds important behavioral context beyond the schema, though it omits potential error conditions.
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 providing distinct value: purpose, context, behavioral detail. Efficient and front-loaded with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main action, admin context, side effects, and password rules. Missing prerequisites like subscriber existence or site context, but acceptable for a focused write tool with no output schema.
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 3. Description reiterates password rules already in schema but adds no new semantics for other parameters. Minimal value added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets a password for a subscriber, specifies it's an admin action for bulk provisioning, and distinguishes from subscriber management siblings by focusing on password operations.
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 context for admin bulk-provisioning and bypass of signup email, which guides when to use. Lacks explicit when-not or alternatives but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a Tool data value. Without subscriberId, writes tool-global (visible to every user of the tool). With subscriberId, writes per-user data — the workhorse for AI agents updating a specific user's personalized dashboard, Kanban board, or state file. value accepts any JSON: object, array, string, number, boolean, or null.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Tool ID or slug | |
| key | Yes | Data key | |
| value | No | JSON value to store | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| subscriberId | No | End-user Subscriber ID to scope the write to. Omit for tool-global. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that it writes data and accepts any JSON. Lacks details on side effects, permissions, idempotency, or success signals. Adequate but not thorough.
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 with clear front-loading of purpose. Every sentence adds value and there is no unnecessary verbiage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, scoping, and data format. No output schema described, but for a write tool this is acceptable. Could mention return value or confirmation, but overall complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 6 parameters. The description adds context for subscriberId ('workhorse for AI agents') and value (accepts any JSON). Adds some value but baseline is 3.
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 it writes a tool data value, distinguishes global vs. per-user with subscriberId, and references specific use cases like updating dashboards. It clearly differentiates from sibling tools like get/delete/list.
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 explains when to use subscriberId (per-user data) and when to omit (tool-global), with concrete examples. Does not state explicit when-not-to-use or mention alternative tools, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture the current state of a site resource so it can be restored byte-for-byte later. Use BEFORE any test write against a customer site — restore returns the resource to the exact pre-test state regardless of what the test write does (null, substitute, partial update, etc.). Snapshots live in MCP wrapper memory for 24 hours; they survive across tool calls within a session but are lost on host restart. Supports scope='settings', 'template', 'page' (requires resourceId), 'post' (requires resourceId), and 'review' (requires resourceId).
| Name | Required | Description | Default |
|---|---|---|---|
| scope | Yes | What to snapshot. 'settings' captures editable site settings (excludes admin-only fields like name/domain that PUT can't restore from an editor key); 'template' captures stylesheet/pageFrame/customHeadHtml; 'page' / 'post' / 'review' capture editable fields of a single resource and require a resourceId. | |
| siteId | No | Override the active site for this snapshot (matches the per-call siteId pattern used by other tools). Must match a siteId from your THINCMS_SITES config. | |
| resourceId | No | Required for scope='page', 'post', or 'review'. The resource ID to snapshot. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes that snapshots live in MCP wrapper memory for 24 hours, survive across tool calls, and are lost on host restart. It also specifies what each scope captures (e.g., settings excludes admin-only fields). It does not cover failure behavior or duplication, but the disclosed traits are substantial.
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 concise (three sentences) and front-loaded with the primary purpose and usage advice. It then efficiently covers scope details and lifetime. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description could mention the return value (e.g., snapshot identifier or handle). However, for a snapshot tool, it covers the essential behavioral aspects (scope, lifetime, usage) and the input schema is fully described. Minor gap on return value prevents a 5.
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%, but the description adds significant value: for scope 'settings' it clarifies that admin-only fields are excluded; for 'page/post/review' it notes editable fields and resourceId requirement. This goes beyond the schema enum descriptions to explain behavior and constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it captures the current state of a site resource for byte-for-byte restoration. It distinguishes from siblings like thincms_restore_snapshot by explaining the use case for pre-test writes. The verb 'capture' and resource 'site resource' are specific, and the description differentiates from other snapshot-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use BEFORE any test write against a customer site' and explains that restore returns exact pre-test state. It also details when resourceId is required for specific scopes. While it doesn't list when not to use, the guidance is clear and actionable for the intended use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Switch the active ThinCMS site. All subsequent API calls will use this site's credentials.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the site to switch to (case-insensitive) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It only discloses the basic effect of switching credentials for subsequent calls, but omits details like whether the switch is session-scoped or persistent, error handling for invalid names, or any side effects.
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 front-loaded sentences with no extraneous words. Every sentence adds value: the first states the action, the second explains the consequence.
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 state-changing tool with one parameter and no output schema, the description covers the core purpose and effect. However, it lacks information on error behavior (e.g., invalid site name) and return value, leaving some gaps for an agent.
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% for the only parameter 'name', which already describes it as a case-insensitive site name. The tool description does not add additional semantic value beyond what the schema provides.
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 uses a specific verb 'Switch' and resource 'active ThinCMS site', clearly indicating the action. It effectively distinguishes this context-switching tool from the many CRUD and management sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states that subsequent API calls will use the switched site's credentials, providing clear context for when to use this tool. However, it does not mention when not to use it or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bulk sync all subscribers to the email platform. Creates tags for lead magnets and pushes all subscribers.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Integration ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It discloses that the tool performs a bulk sync and creates tags, which indicates write behavior. However, it omits details on idempotency, error handling, or whether the operation is synchronous, leaving some behavioral gaps.
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 only two sentences with no extraneous information. It is front-loaded and efficiently communicates the core action, earning a perfect score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema, the description should explain return values or results. It does not. It also lacks details on duration or side effects, making it incomplete for an agent to fully understand the tool's 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?
All 3 parameters are fully described in the input schema (100% coverage), so the description adds no additional parameter-level meaning. The baseline of 3 is appropriate as the schema already does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Bulk sync all subscribers') and the resource ('to the email platform'). It also specifies sub-actions ('Creates tags for lead magnets and pushes all subscribers'), making it distinct from sibling tools like thincms_list_subscribers or thincms_create_integration.
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 does not provide any guidance on when to use this tool versus alternatives, nor does it mention prerequisites or when not to use it. It merely states what the tool does, leaving the agent without context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manually trigger a reviews poll for the active site (same code path the cron uses). Fetches from the configured provider, runs sentiment on new reviews, applies the auto-post rule, and detects drift. Subject to the production-write guard. Optional backfillDaysOverride lets you re-run with a longer history window.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| backfillDaysOverride | No | Override the per-site backfillDays setting for this single run (1-365). | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors: fetching, sentiment analysis, auto-post rule, drift detection, and production-write guard. However, it does not mention rate limits or concurrency behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences front-load the core action and each sentence adds distinct information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing output description (e.g., success status, count of processed reviews) and explicit prerequisites, though the schema parameters and production-write guard help partly.
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 description adds value for backfillDaysOverride by explaining its purpose. siteId and confirmProductionWrite are already well-described in 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?
The description clearly states it triggers a reviews poll for the active site, listing specific actions (fetch, sentiment, auto-post, drift detection) and distinguishes it from siblings that view or manage individual reviews.
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 provides context that it uses the same code path as cron and mentions production-write guard, but does not explicitly contrast with alternative tools like thincms_list_reviews or thincms_get_review.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current template's stats (hash, byte size, line count) for each field. Optionally compare against local files to verify a push landed correctly. Returns match/mismatch with size and line differences.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| comparePageFrameFile | No | Local file to compare against the server's page frame | |
| compareStylesheetFile | No | Local CSS file to compare against the server's stylesheet | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. | |
| compareCustomHeadHtmlFile | No | Local file to compare against the server's custom head HTML |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It describes a read operation ('Get'), but the 'confirmProductionWrite' parameter suggests the tool may perform writes, which contradicts the description's implication. The tool's actual side effects (read vs write) are unclear. It also does not mention authentication requirements or rate limits.
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 concise: three sentences, front-loaded with the main action. No unnecessary words. Every sentence adds value.
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 5 parameters (all optional, but no output schema), the description covers the main purpose and comparison feature. However, it fails to address the presence of the 'confirmProductionWrite' parameter, which contradicts the read-only implication. This gap reduces completeness for safe agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds context by explaining the comparison use case ('verify a push landed correctly') but does not elaborate on parameter specifics beyond what the schema already provides. The schema descriptions are already detailed (e.g., siteId override, confirmProductionWrite purpose).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves template stats (hash, byte size, line count) for each field and optionally compares against local files. This distinguishes it from sibling tools like thincms_get_template (which likely returns the full template object). The verb 'Get' and resource 'current template's stats' are specific.
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 provides a clear use case: 'verify a push landed correctly' by comparing with local files. However, it does not explicitly mention alternatives or when not to use this tool. Since the purpose is specialized, the usage context is adequately implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Round-trip a 1-token prompt to the configured AI provider to confirm the key + model combination works. Returns provider, model, and a tiny sample reply. Admin-only.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explains the tool sends a 1-token prompt and returns a reply, indicating a test call. It does not explicitly state it is read-only or safe to call repeatedly, but the nature of a 'test' implies no side effects. Minor lack of explicit safety statement.
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 two sentences, immediately states the action ('Round-trip a 1-token prompt'), and includes key outcomes and constraints. No redundant 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?
The description covers what the tool does, returns, and who can use it. It does not mention the parameters, but the schema fully describes them. For a simple test tool, this is complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters have detailed descriptions. The tool description adds no extra meaning beyond what is already in the input schema. Baseline score of 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 clearly states the tool 'round-trips a 1-token prompt to confirm the key + model combination works' and specifies it returns provider, model, and sample reply. It is distinct from any sibling tools, which are all data operations, making its purpose unique and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for testing AI provider configuration after setup or when troubleshooting. 'Admin-only' provides a usage constraint. No explicit alternatives are given, but no sibling serves a similar function, so the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Test the email platform connection.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Integration ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not disclose whether the test is read-only, what it does (e.g., sends a test email, verifies credentials), or what happens on success/failure. The agent cannot infer safety or side effects.
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 a single sentence, which is concise, but it lacks structure and detail. It is too brief to be fully helpful, though it does not contain extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three parameters, no output schema, and no annotations, the description should explain the test behavior and return value. It does not, leaving the agent with insufficient context to understand what the tool does beyond the name.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with clear descriptions for all three parameters (id, siteId, confirmProductionWrite). The tool description adds no extra meaning beyond the schema, so 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 clearly states the tool tests an email platform connection, which is a specific verb+resource. However, it does not distinguish it from sibling tools like thincms_sync_integration or thincms_test_ai_connection, and the mention of 'email' seems narrower than the tool name 'test_integration' suggests.
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?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, such as requiring an existing integration, or when not to use it (e.g., for non-email integrations).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Hide a review from the public widget. Sets postStatus='not_posted' and holdReason='editor_unpublished'. Subject to the production-write guard.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Review ID. | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses immediate state changes (postStatus, holdReason) and the production-write guard, but does not mention side effects, required permissions, reversibility, or return behavior (e.g., what the response contains).
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 concise and front-loaded, consisting of two sentences that efficiently convey the action and a critical guard condition. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool without an output schema, the description covers the main intent and state changes. However, it omits any mention of the return value or success/error responses, which would aid completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the parameter descriptions in the schema are already detailed. The description adds no additional meaning to the parameters beyond what the schema provides. Baseline score of 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 clearly states the tool's purpose: 'Hide a review from the public widget.' It also specifies the exact state changes (postStatus and holdReason), which distinguishes it from sibling tools like thincms_publish_review or thincms_get_review.
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 does not explicitly state when to use this tool over alternatives. It mentions a production-write guard but provides no context on prerequisites or when not to use it. Usage can be inferred from the sibling tools, but no direct guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing author profile. Only provided fields are changed.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Author ID (required) | |
| bio | No | Author bio | |
| name | No | Author name | |
| slug | No | URL slug | |
| No | Author email | ||
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| social | No | Social links object | |
| website | No | Author website URL | |
| avatarUrl | No | Avatar image URL | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It only states partial update, but omits authentication, rate limits, idempotency, side effects, or return behavior. Minimal 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?
Two short, front-loaded sentences with zero waste. Directly communicates core purpose and key behavior.
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 having 10 parameters with nested objects, no output schema, and no annotations, the description only covers partial update. Lacks guidance on success/error, prerequisites, and return values.
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 documentation coverage is 100%, so the description does not need to add parameter details. It adds no extra meaning beyond the schema, meeting baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'update' and resource 'author profile', and specifies partial update behavior ('only provided fields are changed'), distinguishing it from create and delete operations.
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 gives clear context (update existing author) and notes partial update, but does not explicitly mention when not to use or suggest alternatives like thincms_create_author or thincms_delete_author.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a draft or scheduled campaign.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Campaign ID | |
| name | No | ||
| listId | No | ||
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| subject | No | ||
| tagFilter | No | ||
| htmlContent | No | ||
| scheduledAt | No | DEPRECATED — use scheduledFor. ISO 8601 timestamp, or null to clear. | |
| scheduledFor | No | Override the schedule: "immediate" or an ISO 8601 timestamp at least 60 minutes in the future. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. However, it only states the update action and allowed campaign states. It does not specify whether updates are partial or full, idempotency, side effects, permissions, or error handling. This is insufficient for a mutation tool with 10 parameters.
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 a single sentence with no redundant words. Every word contributes to understanding the tool's core function. It is appropriately concise.
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 (10 parameters, 1 required), lack of output schema, and no annotations, the description is too sparse. It omits critical context such as success/error responses, confirmation for production writes (despite the confirmProductionWrite parameter), and whether the tool can be applied to canceled or sent campaigns.
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 50% (5 of 10 parameters documented). The tool description adds no parameter-specific information beyond the schema. For the five undocumented parameters (name, listId, subject, tagFilter, htmlContent), the description offers no hints about their purpose, leaving the agent to infer from parameter names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and the resource 'draft or scheduled campaign,' distinguishing it from sibling tools like create, delete, send, and get stats. It specifies the campaign state, adding precision beyond the name alone.
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 the tool is for modifying unsent campaigns (draft or scheduled) but does not explicitly state when not to use it, nor does it mention alternatives like thincms_send_campaign or thincms_get_campaign. Guidance is minimal but not misleading.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing category. Only provided fields are changed.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Category ID (required) | |
| name | No | Category name | |
| slug | No | URL slug | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| parentId | No | Parent category ID | |
| sortOrder | No | Sort order | |
| description | No | Category description | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions 'Only provided fields are changed' indicating partial update (PATCH-like) behavior. However, with no annotations, it lacks details on authorization, side effects, or error conditions. The confirmProductionWrite parameter adds some context but is not referenced in the description.
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 a single efficient sentence that conveys the essential information without any unnecessary words.
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 absence of output schema and annotations, the description adequately covers the core action but lacks detail on return values, error handling, or usage context. For a tool with 8 parameters, it is minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description's mention of 'Only provided fields are changed' reinforces partial update semantics, adding marginal value beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Update an existing category' with the specific resource 'category', and distinguishes from sibling tools like thincms_create_category and thincms_delete_category by implying the update operation.
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 use for updating a category but provides no explicit guidance on when to use this tool versus alternatives (e.g., thincms_create_category for new categories, thincms_delete_category for removal), nor any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update collection settings. Supports partial updates.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Collection ID | |
| name | No | Collection name | |
| slug | No | URL-safe slug | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| columns | No | Grid columns | |
| enabled | No | Whether the collection is active | |
| maxItems | No | Max items to show, 0 = all | |
| showLink | No | Show item links | |
| showImage | No | Show item images | |
| showTitle | No | Show item titles | |
| sortOrder | No | Sort order | |
| schemaType | No | Schema.org type to auto-emit. 'faq' emits FAQPage JSON-LD on pages that render this collection. | |
| showRating | No | Show item ratings | |
| autoAdvance | No | Auto-advance carousel/banner | |
| description | No | Internal description/note | |
| displayMode | No | Display mode | |
| showSubtitle | No | Show item subtitles | |
| advanceInterval | No | Seconds between auto-advance slides | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description notes 'Supports partial updates', indicating the tool can accept partial payloads. No other behavioral traits (e.g., side effects, authorization needs) are disclosed, and annotations are absent, placing the full burden on the description.
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 extremely concise with two sentences, front-loading the action. Every word is necessary and no fluff is present.
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 (19 parameters, no output schema) and lack of annotations, the description is too minimal. It omits important context such as the effect on the system, prerequisite steps, and the required confirmation for production writes (documented in the parameter description for confirmProductionWrite).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions, so the tool description adds no new meaning beyond what the schema already provides. Baseline score of 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 'Update collection settings' uses a specific verb and resource, clearly indicating the tool's action. It distinguishes itself from sibling tools like thincms_create_collection, thincms_get_collection, thincms_delete_collection, and thincms_update_collection_item.
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?
No explicit usage guidelines are provided; the description does not state when to use this tool versus alternatives like create or delete, nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a collection item. Supports partial updates.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Main content text or HTML | |
| title | No | Item title | |
| itemId | Yes | Item ID | |
| rating | No | Rating 1-5 | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| enabled | No | Whether item is visible | |
| linkUrl | No | Link URL | |
| imageUrl | No | Image URL | |
| linkText | No | Link button text | |
| subtitle | No | Subtitle | |
| sortOrder | No | Sort order | |
| collectionId | Yes | Collection ID | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. Mentions partial updates but lacks details on permissions, idempotency, return value, or side effects. The confirmProductionWrite parameter in schema is not referenced.
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 succinct sentences, no filler. Every word adds value. Front-loaded with purpose.
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?
Lacks output schema and the description doesn't explain return values. For a 13-parameter update tool, missing behavioral context like confirmation for production writes (though schema mentions it) and expected outcome.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions (e.g., siteId). The description adds no additional meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a collection item' with a specific verb and resource, distinguishing it from create, delete, and reorder siblings. 'Supports partial updates' adds useful nuance.
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?
No guidance on when to use this tool versus alternatives like create_collection_item or delete_collection_item. Given many sibling tools, explicit context would help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing content block. Supports partial updates — only include fields you want to change.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Content block ID | |
| name | No | Display name | |
| slug | No | URL-safe slug | |
| type | No | Switch the block type. Switching to a typed widget clears the HTML content unless you pass content explicitly. | |
| config | No | JSON config blob for typed widgets. Pass empty string or null to clear. | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| content | No | HTML content (type='html' blocks) | |
| enabled | No | Whether the block is active | |
| sortOrder | No | Sort order | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It only mentions 'partial updates' but fails to disclose important behaviors such as the clearing of content when switching type (noted in schema but not description), production write confirmation requirements, or potential side effects. This is insufficient for a 10-parameter mutation 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?
The description is very short and front-loaded with key information. However, it may be too concise for a complex tool; a bit more context without being verbose would improve 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?
Given 10 parameters, no output schema, and no annotations, the description lacks context on return values, error handling, or detailed implications of updating fields. It is incomplete for an update operation with significant behavior (e.g., type switching, site overrides).
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 description does not need to add parameter details. Baseline 3 applies as the description adds no extra meaning beyond 'partial updates' which is already implied by the semantics of an update operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Update an existing content block' with the verb 'update' and resource 'content block'. It distinguishes from sibling tools like create, delete, and get by its purpose.
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 for modifying existing blocks via 'partial updates' but does not explicitly state when to use this tool versus alternatives like create or delete. However, the CRUD context among siblings makes it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing course. Only provided fields are changed (partial update).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Course ID (required) | |
| slug | No | URL slug | |
| title | No | Course title | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| status | No | Course status | |
| summary | No | Short plain-text blurb | |
| dripMode | No | Content drip mode | |
| accessMode | No | How learners gain access | |
| courseType | No | Type: 'course' or 'community' | |
| description | No | Full HTML landing page content | |
| thumbnailUrl | No | Thumbnail image URL | |
| priceCurrency | No | Currency code | |
| showInCatalog | No | Show on public course catalog | |
| priceAmountCents | No | Price in cents | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses partial update behavior (only provided fields changed) but omits other traits like authorization needs, rate limits, or side effects. The parameter confirmProductionWrite hints at production safety but is not mentioned in the description.
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 concise sentences with no waste. The purpose is front-loaded, and every word adds value.
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 has 15 parameters and no output schema, the description is minimal. It does not explain return values, provide usage examples, or mention prerequisites (e.g., fetch course first). Schema covers parameters, but overall completeness is adequate.
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 no parameter-specific meaning beyond the schema; 'partial update' is a general behavior not tied to individual parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an existing course and specifies it is a partial update. This distinguishes it from sibling tools like thincms_create_course (creates new) and thincms_delete_course (removes), providing specific verb+resource scope.
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 for modifying course fields but does not explicitly state when to use this tool versus alternatives (e.g., thincms_create_course for new courses) or provide exclusions. The partial update hint is helpful but lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an enrollment status. Use to approve pending enrollments or revoke access.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Enrollment ID (required) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| status | Yes | New status (required) | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states 'Update an enrollment status' without disclosing side effects, permissions, reversibility, or safety considerations like the confirmProductionWrite parameter. This is insufficient for a mutation 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?
The description is only two sentences, front-loading the action and then the use cases. Every word is necessary and there is no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool (4 parameters, no output schema), the description covers core functionality but lacks operational context such as the need for a valid enrollment ID, the effect of siteId and confirmProductionWrite, and the fact that status changes may be irreversible. This is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage for all parameters, so the baseline is 3. The tool description does not add additional meaning beyond the schema; it repeats the status change intent but provides no extra context for parameters like siteId or confirmProductionWrite.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and the resource 'enrollment status', and specifies use cases: approving pending enrollments or revoking access. It distinguishes from sibling tools like thincms_create_enrollment, thincms_delete_enrollment, and thincms_list_enrollments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use to approve pending enrollments or revoke access,' which clearly indicates when to use this tool. However, it does not mention when not to use it or provide alternatives, but the context is clear enough for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing form or survey. Only provided fields are changed. For large HTML content (>10KB), use htmlContentFile instead of htmlContent.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Form ID (required) | |
| name | No | Form name | |
| slug | No | URL slug | |
| fields | No | Field definitions | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| enabled | No | Enable/disable form | |
| renderMode | No | Render mode | |
| webhookUrl | No | Webhook URL | |
| description | No | Form description | |
| htmlContent | No | Custom HTML content | |
| successMessage | No | Success message | |
| webhookUrlTest | No | Test webhook URL | |
| htmlContentFile | No | Local file path containing HTML content — use this instead of htmlContent for large surveys (>10KB). | |
| webhookTestMode | No | Enable test mode | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral disclosure burden. It discloses that only provided fields are changed (partial update) and advises on large content handling. Missing details include idempotency, side effects, authorization needs, and whether unprovided fields are preserved or reset.
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 two sentences long, front-loads the core purpose, and immediately follows with a critical usage note. Every sentence is informative with no wasted words.
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 complexity (15 parameters, no annotations, no output schema), the description is minimal. It covers the core purpose and partial update behavior but omits return value (assume updated form), error handling, prerequisites (form must exist), and concurrency implications. The rich schema compensates somewhat, but the description could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already defines all parameters. The description adds value beyond the schema by explaining the partial update behavior ('Only provided fields are changed') and providing guidance on when to use htmlContentFile vs htmlContent. This helps the agent select the correct parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing form or survey,' specifying the verb (update) and resource (form/survey). It distinguishes from sibling tools like thincms_create_form (create) and thincms_get_form (read), and clarifies partial update with 'Only provided fields are changed.'
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 provides a specific guideline for large HTML content (use htmlContentFile >10KB). However, it does not explicitly state when not to use this tool or how it compares to alternative tools like create_form or delete_form. No prerequisites or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the email platform integration config.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Integration ID | |
| name | No | Updated name | |
| config | No | Updated config | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| enabled | No | Enable/disable | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description must disclose behavioral traits. It only states 'Update', implying a write operation, but does not explain if it overwrites config, triggers side effects, or requires special permissions. The critical field confirmProductionWrite is not referenced.
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 a single, clear sentence with no wasted words. It could be structured to include more context (e.g., return value), but it is appropriately concise for a simple update.
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 write operation with 6 parameters and no output schema, the description lacks completeness. It does not mention the result of the update, the need for confirmProductionWrite, or any side effects. The sibling tool thincms_get_integration might be needed to inspect before updating, but that is absent.
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 input schema already documents all 6 parameters. The description adds no additional parameter semantics, meeting the baseline of 3.
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 uses the specific verb 'Update' and clearly identifies the resource as 'email platform integration config'. It distinguishes this tool from siblings like thincms_get_integration and thincms_create_integration.
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?
No guidance is given on when to use this tool versus alternatives, such as thincms_create_integration or thincms_get_integration. Prerequisites like having an integration ID or acknowledging production writes via confirmProductionWrite are not mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing lead magnet. Supports partial updates.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Lead magnet ID (required) | |
| slug | No | URL slug | |
| title | No | Lead magnet title | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| ctaText | No | CTA button text shown on the resources page (e.g., 'Join the webinar', 'Take the survey') | |
| enabled | No | Enable/disable lead magnet | |
| mediaId | No | Media ID of the downloadable file | |
| formSlug | No | Form slug | |
| sortOrder | No | Sort order | |
| landingUrl | No | Custom landing URL override. When set, resource cards link here instead of /resources/:slug. | |
| description | No | Description | |
| thumbnailUrl | No | Thumbnail image URL | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Mentions partial updates but lacks details on side effects, error conditions, required permissions, or idempotency.
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 fluff, efficient and front-loaded.
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 13 parameters and no output schema or annotations, the description is too sparse. Fails to explain response format, error handling, or how partial updates work in practice.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with thorough descriptions, so the tool description adds minimal extra value beyond stating 'partial updates'. 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?
Clearly states the action 'Update' and the resource 'lead magnet', with 'Supports partial updates' adding nuance. Distinct from create and delete 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?
No guidance on when to use this tool vs alternatives (e.g., create vs update), no prerequisites or context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing lesson. Only provided fields are changed (partial update). For large content (>10KB), use contentFile.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Lesson ID (required) | |
| slug | No | URL slug | |
| title | No | Lesson title | |
| isFree | No | Free preview lesson | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| content | No | HTML content | |
| dripDate | No | ISO date for scheduled drip | |
| duration | No | Recording duration in seconds | |
| videoUrl | No | Video embed URL | |
| isUnlocked | No | Manually unlock this lesson | |
| contentFile | No | Local file path containing HTML content | |
| recordingDate | No | ISO date when the live session was held | |
| videoDuration | No | Video duration | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits fully. It mentions partial update and a size limit, but omits critical details like idempotency, error behavior (e.g., missing lesson), permission needs, or the site override impact. For a mutation tool with 14 parameters, this is insufficient.
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 concise sentences with no fluff. Critical information is front-loaded: update action, partial nature, and a key usage hint. Every word 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?
Given the tool's complexity (14 parameters, no output schema, no annotations), the description is too sparse. It lacks context about site scoping, production write safeguards, required confirmations, and what happens on failure. The agent would need to inspect schema details heavily.
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% (all parameters described). The description adds value beyond schema by explaining the partial update behavior and the content size threshold, which is not apparent from individual parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates an existing lesson with partial update semantics. It's specific about the verb and resource, but does not explicitly differentiate from other update tools (e.g., thincms_update_course) among the many 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?
The description gives a usage hint for large content (>10KB) via contentFile, indicating when to choose that parameter over content. However, it does not provide when-not-to-use guidance or alternatives beyond that specific scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update media metadata (alt text, caption, visibility). Does not change the file itself.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Media ID (required) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| altText | No | Alt text for accessibility | |
| caption | No | Image caption | |
| visibility | No | Visibility | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. States it updates metadata and does not change the file, but lacks details on side effects, idempotency, permission requirements, or return value. For a mutation tool, essential behavioral traits are undisclosed.
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 concise sentences. Front-loaded with the primary action. No redundant or vague wording. Every word adds value.
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 metadata update tool with full schema coverage, the description provides the core purpose. However, it omits context like response shape, error cases, or multi-tenant behavior (though siteId parameter is documented). Lacks completeness for a tool with 6 parameters and no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions (e.g., siteId, confirmProductionWrite). The description lists only a subset of fields (alt text, caption, visibility), adding no meaningful information beyond the schema. Baseline 3 applies as schema already provides adequate semantics.
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?
Clearly states 'Update media metadata (alt text, caption, visibility). Does not change the file itself.' This specifies the action, the resource (media), and explicitly distinguishes from upload/delete operations. Siblings like thincms_upload_media, thincms_delete_media are 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?
The description implies usage for metadata-only updates but does not explicitly state when to use this versus alternatives (e.g., thincms_upload_media for file changes). No prerequisites or conditions are mentioned. The context is clear but guidance is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a module's title or description.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Module title | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| courseId | Yes | Course ID (required) | |
| moduleId | Yes | Module ID (required) | |
| description | No | Module description | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It only says 'Update', implying a write operation, but does not disclose permissions, destructive nature, rate limits, or side effects. The presence of confirmProductionWrite in the schema hints at production safety, but the description ignores this.
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 a single, concise sentence that immediately conveys the tool's purpose. No redundant words or information. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 6 parameters, no output schema, and no annotations, the description is too sparse. It does not explain return values, required preconditions (e.g., module existence), or consequences of update. The confirmProductionWrite parameter hints at production write safety, but the description offers no completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, meaning each parameter is already described in the input schema. The description adds no new semantics beyond listing 'title or description'. For high coverage, baseline is 3; the description neither improves nor reduces understanding.
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 'Update a module's title or description' clearly states the action (update) and resource (module) and specifies which fields can be updated. It distinguishes from sibling tools like thincms_create_module and thincms_delete_module. However, it does not mention that siteId and confirmProductionWrite are also part of the input, though these are auxiliary parameters.
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?
No usage guidance is provided. The description does not indicate when to use this tool versus alternatives (e.g., thincms_create_module for new modules, thincms_delete_module for removal). There is no mention of prerequisites or context for updates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing static page. Only provided fields are changed (partial update). Content should be raw HTML. For large content (>10KB), use contentFile instead of content. Changing slug auto-creates a 301 redirect from the old URL.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Page ID (required) | |
| slug | No | URL slug | |
| title | No | Page title | |
| jsonLd | No | Custom JSON-LD (Schema.org) injected verbatim into the page <head>. Pass valid JSON as a string. Use for Service, Event, BreadcrumbList, HowTo, Article, etc. Set to empty string to clear. | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| status | No | Page status | |
| content | No | HTML content | |
| noIndex | No | Set true to add noindex meta tag | |
| metaTitle | No | SEO meta title | |
| ogImageUrl | No | Open Graph image URL | |
| renderMode | No | Render mode | |
| contentFile | No | Local file path containing HTML content — use this instead of content for large pages (>10KB). | |
| canonicalUrl | No | Canonical URL | |
| metaDescription | No | SEO meta description | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It clearly communicates the partial update nature, the content format requirement, the alternative for large content (contentFile), and the automatic redirect on slug change. This is good coverage for a mutation tool, though it could mention potential side effects like re-indexing.
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 highly concise with only two sentences, covering the core purpose and key behavioral notes without extraneous details. Information is front-loaded with the primary action and partial update characteristic.
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 15 parameters, no output schema, and no annotations, the description covers the essential aspects: update operation, partial update, content format, size guidance, redirect behavior, and siteId override (mentioned in schema). It lacks details on return value or error conditions but is sufficient for an update tool among many siblings.
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 explains each parameter. The description adds marginal value by clarifying the relationship between 'content' and 'contentFile' (size threshold) and the redirect behavior tied to 'slug'. For a tool with complete schema descriptions, this is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and resource 'existing static page', specifying partial update behavior, content format (raw HTML), size guidance, and implicit side effect (auto-redirect on slug change). This sufficiently distinguishes it from siblings like create_page, delete_page, and get_page.
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 through its update verb and mentions partial update, content size considerations, and redirect behavior. However, it does not explicitly state when to use this tool over similar update tools (e.g., thincms_update_post) or provide alternative scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing popup. Only provided fields are changed.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Popup ID (required) | |
| name | No | Popup name | |
| slug | No | URL slug | |
| formId | No | Form ID | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| enabled | No | Enable/disable | |
| bodyText | No | Body text | |
| headline | No | Headline text | |
| priority | No | Priority level | |
| customCss | No | Custom CSS | |
| targeting | No | Page targeting rules | |
| displayType | No | Display type | |
| suppressDays | No | Days to suppress after dismiss | |
| ctaButtonText | No | CTA button text for the two-step popup flow | |
| mobileEnabled | No | Show on mobile | |
| triggerConfig | No | Trigger configuration | |
| mobileDisplayType | No | Mobile display override | |
| suppressOnConvert | No | Days to suppress after conversion | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It reveals it is a mutation (update) and partial update, but does not disclose required permissions, reversibility, side effects, or response structure. The schema is rich but the description adds little beyond the obvious.
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 extremely concise: two sentences front-loading the purpose and key behavioral trait. Every sentence earns its place with zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the rich schema, the description lacks completeness for a complex tool with 19 parameters and no output schema. It does not describe return values, error scenarios, or the effect on existing popup state beyond the update. The agent is left with many unanswered questions.
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 the critical nuance 'Only provided fields are changed' which explains the partial update semantics not evident from individual parameter descriptions. This justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing popup', specifying the verb (update) and resource (popup). It also adds 'Only provided fields are changed', which distinguishes it from the create and delete siblings by indicating partial update behavior.
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 provides no guidance on when to use this tool versus alternatives like create or delete. It does not mention prerequisites, when to avoid using it, or any context for selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing blog post. Only provided fields are changed (partial update). Content should be raw HTML. For large content (>10KB), use contentFile instead of content. Changing slug auto-creates a 301 redirect from the old URL.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Post ID (required) | |
| slug | No | URL slug (changing slug auto-creates a 301 redirect) | |
| tags | No | Array of tag names (full replacement) | |
| title | No | Post title | |
| jsonLd | No | Custom JSON-LD (Schema.org) injected verbatim into the post <head>. Pass valid JSON as a string. Set to empty string to clear. | |
| series | No | Series name | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| status | No | Post status | |
| content | No | HTML content | |
| excerpt | No | Short summary/excerpt | |
| noIndex | No | Exclude from search engine indexing | |
| authorId | No | Author ID | |
| featured | No | Mark as featured | |
| metaTitle | No | SEO meta title | |
| ogImageUrl | No | Open Graph image URL | |
| categoryIds | No | Array of category IDs (full replacement) | |
| contentFile | No | Local file path containing HTML content — use this instead of content for large posts (>10KB). | |
| gatePreview | No | Custom HTML teaser shown before the gate. | |
| pinnedUntil | No | ISO date: pin until this date | |
| publishedAt | No | DEPRECATED — use scheduledFor. ISO date for publication date. | |
| scheduledAt | No | DEPRECATED — use scheduledFor. Legacy field. | |
| seriesOrder | No | Order within series | |
| canonicalUrl | No | Canonical URL | |
| scheduledFor | No | Override visibility timing. "immediate" or an ISO 8601 timestamp at least 60 minutes in the future. | |
| gatedFormSlug | No | Form slug to gate this post behind. Set to empty string to remove gating. | |
| membersContent | No | HTML content visible only to authenticated members/subscribers. | |
| metaDescription | No | SEO meta description | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and covers key behaviors: partial update (PATCH semantics), content format requirement, file alternative for large content, and automatic 301 redirect. Could mention authentication or idempotency but these are not critical.
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?
Only three sentences, each adding distinct value: statement of operation, content guidance, and behavior note. No fluff, front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 28 parameters and no output schema, the description covers the essential behavioral context. It explains partial update, content handling, and slug redirect, which are enough for an agent to use the tool correctly. Minor omission of error handling or idempotency.
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 value by explaining partial update semantics, content format constraint, and slug side-effect, which enriches parameter meaning beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update an existing blog post') and the resource ('blog post'). It specifies partial update semantics and distinguishes from creation/deletion siblings. The mention of raw HTML and slug redirects adds specificity.
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 clear guidance on when to use contentFile instead of content for large posts (>10KB) and the auto-redirect on slug change. Lacks explicit when-not-to-use or alternative tools, but the partial update nature is implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a quiz. Only provided fields are changed.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Quiz ID (required) | |
| slug | No | URL slug | |
| title | No | Quiz title | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| feedbackMode | No | Feedback mode | |
| passingScore | No | Passing score percentage | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. The description only states that it updates and that only provided fields change; it does not disclose side effects, authorization needs, idempotency, or what happens if the quiz does not exist.
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 extremely concise: two sentences, no filler, directly to the point. Every word is necessary.
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 that there is no output schema and the tool performs a mutation, the description lacks critical context: return value, error scenarios, prerequisites (e.g., quiz existence), and usage patterns. The completeness is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 7 parameters with descriptions (100% coverage). The description adds no parameter-specific information beyond what is already in the schema, so it meets the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the resource ('a quiz'), and explicitly notes that only provided fields are changed (partial update). However, it does not differentiate from sibling tools like create_quiz or delete_quiz, which diminishes clarity.
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?
No guidance on when to use this tool versus alternatives (e.g., create_quiz, delete_quiz). There is no mention of prerequisites, limitations, or context for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a quiz question. Only provided fields are changed.
| Name | Required | Description | Default |
|---|---|---|---|
| quizId | Yes | Quiz ID (required) | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| options | No | Array of 2-5 answer option strings | |
| sortOrder | No | Position within the quiz | |
| questionId | Yes | Question ID (required) | |
| explanation | No | Explanation shown after answering | |
| correctIndex | No | Index of the correct answer (0-based) | |
| questionText | No | The question text | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description mentions partial update but lacks details on permissions, validation, side effects, or error conditions. For a mutation tool, more behavioral disclosure is needed.
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. Front-loaded with main purpose, then clarifying partial update. Efficient and focused.
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 9 parameters and no output schema, the description adequately states purpose but doesn't cover return values, error behavior, or prerequisites (e.g., quiz must exist). Not fully complete but sufficient for a straightforward update.
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?
All parameters have individual descriptions in the schema (100% coverage). The description adds minimal extra meaning ('Only provided fields are changed') but doesn't elaborate on parameter semantics beyond what schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update a quiz question') and the resource (quiz question), and implies partial update ('Only provided fields are changed'). It distinguishes from sibling tools like add/delete quiz question.
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?
No explicit guidance on when to use vs alternatives (e.g., add_quiz_question, delete_quiz_question). The purpose is clear but usage context 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.
Update an existing redirect. Only provided fields are changed.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Redirect ID (required) | |
| note | No | Admin note | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| enabled | No | Enable/disable | |
| targetUrl | No | New target URL | |
| sourcePath | No | New source path | |
| statusCode | No | 301 or 302 | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It only says 'Update' (implying mutation) and 'Only provided fields are changed' (implying partial update). Missing details on required permissions, idempotency, error behavior, or side effects.
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, front-loaded sentences with no unnecessary words. Every sentence adds meaningful 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?
The tool has 8 parameters and no output schema. The description covers the core update behavior but lacks information about return values, error handling, or prerequisites. It is minimally adequate for a partial update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters already have descriptions. The description adds value by clarifying that only provided fields are changed (partial update), which is key context not in the schema. This helps the agent understand that omitted fields remain unchanged.
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 explicitly states 'Update an existing redirect', clearly identifying the verb (update) and resource (redirect). The phrase 'Only provided fields are changed' distinguishes it from create, delete, get, list, and import redirect tools among 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?
No guidance on when to use this tool versus alternatives such as create_redirect, delete_redirect, or get_redirect. No mention of prerequisites, typical scenarios, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update reviews module + AI provider configuration. Partial-update — only provided fields change. Pass an empty string to a key field (e.g. reviews.outscraperApiKey='') to clear that secret. Admin-only; subject to production-write guard.
| Name | Required | Description | Default |
|---|---|---|---|
| ai | No | ||
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| reviews | No | ||
| recipientUserIds | No | Replace the list of users who receive the daily digest. Each ID must be an existing site user. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. Discloses partial-update semantics, secret clearing mechanism, admin restriction, and production-write guard. Could be more specific about idempotency or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: three sentences with front-loaded action. No wasted words; every sentence adds essential 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?
With no output schema, description should explain return value or side effects; it does not mention what the function returns. Covers mutation and guards well, but omits result 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 covers 60% of parameters with descriptions. The description adds value by explaining that empty strings clear secrets and that confirmProductionWrite acknowledges production writes, but does not detail each parameter beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update reviews module + AI provider configuration' with a specific verb and resource. It distinguishes itself from siblings like thincms_get_reviews_settings by being the update variant.
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 explicit usage guidance: partial-update behavior, clearing secrets with empty strings, admin-only access, and production-write guard. Lacks explicit when-not-to-use or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing script injection. Only provided fields are changed.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Script ID (required) | |
| code | No | Script code including <script> tags | |
| name | No | Script name | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| enabled | No | Enable/disable the script | |
| placement | No | Where to inject | |
| sortOrder | No | Sort order | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states 'Update' without mentioning side effects, permissions, rate limits, or error conditions. The confirmProductionWrite parameter is described in the schema but not in the description, leaving the agent unaware of production safety constraints.
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 a single concise sentence that is front-loaded with the action and resource. Every word is necessary; no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters, no output schema, and no annotations, the one-sentence description is insufficient. It omits return behavior, error scenarios, and interactions with other tools (e.g., thincms_switch_site). The detailed siteId description in the schema partially compensates, but the overall description lacks completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter's meaning is documented. The description adds the key insight that only provided fields are changed (PATCH semantics), which goes beyond schema. However, it does not elaborate on individual parameters beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates an existing script injection and uses a specific verb ('Update') with a resource ('script injection'). It distinguishes from sibling tools like thincms_create_script and thincms_list_scripts by specifying the update action.
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 use for updating existing scripts but does not explicitly state when to use versus alternatives (e.g., thincms_create_script for new scripts). The partial update behavior is mentioned, but no guidance on prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a sequence's name or trigger form.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Sequence ID | |
| name | No | ||
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| triggerFormSlug | No | ||
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only says 'Update' which implies mutation but provides no details on side effects, permissions, rate limits, or error behavior. With no annotations to compensate, the agent lacks critical behavioral 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 very concise, consisting of a single sentence that conveys the core purpose without unnecessary words. However, it could be slightly more structured by listing the updatable fields.
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 description is minimal and fails to provide context about return values, error handling, or preconditions. Given the tool has 5 parameters and no output schema, more details are needed for complete understanding.
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 description does not explain the parameters beyond mentioning 'name or trigger form'. Schema coverage is 60%, and the description adds no additional meaning to the parameters; for instance, it doesn't clarify the format or constraints of name or triggerFormSlug.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the resource ('a sequence'), and specifies the fields that can be updated ('name or trigger form'). This distinguishes it from sibling tools like create, delete, or publish.
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?
No guidance is provided on when to use this tool versus alternatives like thincms_create_sequence or thincms_publish_sequence. There is no mention of prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a sequence step.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| stepId | Yes | Step ID | |
| subject | No | ||
| delayDays | No | ||
| sequenceId | Yes | Sequence ID | |
| htmlContent | No | ||
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It only states the action without mentioning idempotency, whether it performs partial updates (implied by optional schema fields but not stated), required permissions, or side effects. This is insufficient for an agent to understand the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but severely under-specified. Given the tool has 7 parameters and multiple siblings, the description should include more structured information (e.g., a list of updatable fields) without being verbose.
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 description is extremely incomplete for a tool with 7 parameters, no output schema, and no annotations. It does not mention return values, the scope of updates, or how the tool relates to other sequence operations. An agent cannot effectively use this tool based solely on the provided description.
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 description adds no meaning beyond the input schema. While schema coverage is 57%, three parameters (subject, delayDays, htmlContent) lack descriptions in both schema and tool description. The tool description does not list or explain any parameters, failing to compensate for the schema gaps.
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 'Update a sequence step' clearly states the verb and resource, but it is vague and does not distinguish this tool from other update tools like 'thincms_update_sequence' or 'thincms_update_post'. The name already implies the resource, so the description adds little value.
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 provides no guidance on when to use this tool versus alternatives such as 'thincms_add_sequence_step', 'thincms_delete_sequence_step', or 'thincms_update_sequence'. No context about prerequisites or best practices is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update site settings. Supports partial updates — only provided fields are changed. Sensitive fields (SMTP, Stripe keys, API keys, billing) remain admin-only.
| Name | Required | Description | Default |
|---|---|---|---|
| locale | No | ISO locale code (e.g. 'en-NZ', 'en-US', 'en-GB', 'fr-FR', 'de-DE'). Drives date/time/number formatting on the public site. Empty defaults to en-US at render time. | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| aiBrief | No | Customer-authored 'AI brief' — voice/positioning/about content rendered in the auto-generated /llms.txt under an 'About' heading. Use this for narrative content that doesn't fit the structured LocalBusiness fields. Set to empty string to clear. | |
| logoUrl | No | Path or absolute URL of the site logo (used by {{site:logo}} and Organization JSON-LD). | |
| tagline | No | Short site tagline (e.g. shown under the site name in headers/OG tags). | |
| business | No | LocalBusiness / structured data. Used to auto-emit Schema.org JSON-LD on the homepage. Partial-update — only provided sub-fields change. | |
| timezone | No | IANA timezone (e.g. 'Pacific/Auckland', 'Europe/London', 'America/New_York'). Used for the timeZone property on LocalBusiness OpeningHoursSpecification and any future timezone-sensitive rendering. Empty defaults to Etc/UTC. | |
| faviconUrl | No | Path or absolute URL of the site favicon. | |
| ogImageUrl | No | Site-wide default Open Graph image URL. Used as the OG image when a page or post doesn't set its own ogImageUrl. Per-page values override this fallback. | |
| description | No | Site description used for meta description, OG tags, and structured data. | |
| emitLlmsTxt | No | Whether to auto-generate /llms.txt for this site (default true). When false, /llms.txt returns 404. | |
| googleTagId | No | Google tag ID for analytics — gtag.js (G-/AW-/GT-) or GTM container (GTM-). The correct snippet is injected into <head> automatically. Set to empty string to clear. | |
| memberFormSlug | No | Form slug used for membership/subscriber signup. Set to empty string to disable membership signup. | |
| robotsAdditions | No | Free-text rules appended to the auto-generated /robots.txt. Use to opt specific user-agents in or out (e.g. 'User-agent: GPTBot\nDisallow: /' to block OpenAI's training crawler). Set to empty string to clear. | |
| bingVerification | No | Bing Webmaster Tools verification token (rendered as <meta name="msvalidate.01">). | |
| googleVerification | No | Google Search Console verification token (rendered as a meta tag). | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses partial updates and admin-only restrictions on sensitive fields, which adds value beyond the schema. However, with no annotations provided, more detail on side effects, error handling, or idempotency would improve transparency.
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 fluff, front-loaded with key behavioral info (partial updates, sensitive field restriction). Every sentence 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 tool with 17 parameters and no annotations or output schema, the description is too sparse. It does not cover return value, error scenarios, or confirmation requirements (e.g., confirmProductionWrite is documented in schema but not mentioned in description).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The description adds a high-level note about sensitive fields being admin-only, but this is not parameter-specific. Baseline 3 applies as schema already does heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates site settings and mentions partial updates. It distinguishes from a read tool (thincms_get_settings) but does not explicitly separate from other update tools, though the name and resource are 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?
No guidance on when to use this tool vs alternatives. The only hint is that sensitive fields are admin-only, but no context on when to prefer this over other updates or what prerequisites (like switching sites) are needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace the site's social media links (max 20). Each link needs a platform and URL. Supported platforms: linkedin, twitter, youtube, facebook, instagram, tiktok, github, email, website, custom. Use {{social:links}} in the page frame template to render them.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| socialLinks | Yes | Social media links array (full replacement) | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says 'Replace' which implies overwriting the entire set of social links, and mentions 'max 20' constraint. Since no annotations are provided, the description carries the full burden of behavioral disclosure, but it does not detail side effects such as immediate propagation or irreversibility.
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 extremely concise with two sentences that front-load the essential purpose and constraint, followed by a helpful usage hint. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and detailed schema, the description is largely complete. It explains the replacement action, maximum count, platform options, and template usage. Minor omission: it doesn't explicitly state that it is a full replacement, but the schema's 'full replacement' note covers this.
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 value by explaining that each link requires a platform and URL, listing supported platforms, and noting the rendering method, which provides context beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool replaces the site's social media links, specifying the max of 20 and listing supported platforms. This distinguishes it from related tools like thincms_get_social_links.
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 indicates when to use the tool ('Replace the site's social media links') and provides a usage tip ('Use {{social:links}} in the page frame template'). However, it does not mention when not to use it or specify alternatives, but for a simple update tool this is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a tag's name, slug, or description.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Tag ID (required) | |
| name | No | Tag name | |
| slug | No | URL slug | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| description | No | Tag description (displayed on tag archive page) | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description should fully disclose behavior. It simply states what is updated but does not mention side effects, authorization requirements, idempotency, or return behavior. Important details like whether partial updates are supported are missing.
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?
One concise sentence that front-loads the purpose. It is efficient but at the cost of omitting useful 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?
The description covers only 3 of 6 parameters (id, siteId, confirmProductionWrite are missing). It does not mention the output or return value. For a mutation tool with no output schema, more detail is expected.
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 baseline is 3. The description adds no value beyond the parameter descriptions in the schema; it merely repeats three of them. No additional semantic context is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Update) and resource (a tag) and lists the updatable fields (name, slug, description). It distinguishes the tool from other update tools by naming the resource.
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?
No guidance on when to use this tool vs alternatives (e.g., thincms_create_tag, thincms_delete_tag). No prerequisites or context are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the site's template. Only provided fields are changed. The pageFrame must contain {{content}} if provided. For large files (>10KB), use the File variants instead of inlining content. Available template tags: {{content}}, {{nav:header}}, {{nav:footer}}, {{site:name}}, {{site:tagline}}, {{site:logo}}, {{year}}, {{search:form}}.
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| pageFrame | No | HTML page frame with template tags (must include {{content}}) | |
| stylesheet | No | CSS stylesheet for the public site | |
| pageFrameFile | No | Local file path containing the page frame HTML. Use instead of pageFrame for large files. | |
| customHeadHtml | No | Custom HTML injected into <head> (fonts, meta tags, etc.) | |
| stylesheetFile | No | Local file path containing the CSS stylesheet. Use instead of stylesheet for large files (>10KB). | |
| customHeadHtmlFile | No | Local file path containing custom head HTML. Use instead of customHeadHtml for large files. | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose all behavior. It notes partial update ('Only provided fields are changed') and pageFrame must contain {{content}} if provided. However, it omits side effects, permissions, idempotency, response format, and concurrency details.
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 a single paragraph of four sentences, front-loaded with the core purpose. Every sentence adds essential information without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should mention return behavior or success indicators. It covers partial update and file size thresholds but lacks confirmation of what happens after update (e.g., returns updated template). Adequate but with gaps.
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%, providing baseline 3. The description adds value beyond schema by explaining the {{content}} requirement for pageFrame, file variants for large files, and listing template tags. This enriches parameter meaning without detailing each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update the site's template' (specific verb+resource) and distinguishes from sibling tools like thincms_get_template by focusing on updates. It also details partial update behavior and template constraints.
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 provides guidance for large files (>10KB) to use file variants instead of inline parameters, but lacks explicit when-not-to-use instructions or alternatives like thincms_append_css for appending CSS. Basic context is present but incomplete for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing Tool. Only supplied fields change. For large HTML payloads (>10KB), use htmlFile instead of html.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Tool ID or slug (required) | |
| html | No | Raw HTML/JS payload | |
| name | No | ||
| slug | No | URL slug | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| status | No | ||
| aiModel | No | ||
| enabled | No | ||
| htmlFile | No | Local file path containing the HTML payload — use instead of html for large tools | |
| rateLimit | No | Pass null to clear the rate limit | |
| allowSignup | No | ||
| description | No | ||
| authRequired | No | ||
| systemPrompt | No | ||
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description should fully disclose behavioral traits. It only mentions partial update and large payload handling, but omits auth requirements, rate limits, error handling, return value, or effects of updating non-existent tools.
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 very concise with two sentences, the first stating purpose and the second providing a specific usage hint. No unnecessary words.
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 complexity (15 parameters, no output schema, no annotations), the description is insufficient. It does not explain return values, error states, prerequisite steps, or integration with other tools like thincms_get_tool or thincms_list_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?
With only 47% schema description coverage, the description adds marginal value beyond the schema by noting the htmlFile alternative for large payloads. For a 15-parameter tool, more parameter guidance would be beneficial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing Tool' with a specific verb and resource. It distinguishes itself from sibling tools like create, get, list, and delete by the action and the partial update semantics ('Only supplied fields change').
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 provides explicit guidance for large HTML payloads, advising to use htmlFile instead of html. However, it does not discuss when to use this tool versus alternatives like create or delete, which is implied by context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a workbook (partial — only provided fields change). If fields is provided and differs from the current spec, the workbook's version is incremented and any removed-field values in existing responses are archived (not deleted).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Workbook ID (required) | |
| slug | No | URL slug | |
| title | No | Workbook title | |
| fields | No | Ordered array of field definitions. Each field is an object with at minimum { fieldId, type, label }. v1 field types: short_text, long_text, number, rating, select, multi_select, date, prompt_display, markdown_display. Input fields may include `prefillFrom: { courseSlug, workbookSlug, fieldId }` for cross-workbook references. | |
| isFree | No | ||
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| dripDate | No | ||
| sortOrder | No | Position within the module (shared with lessons and quizzes) | |
| fieldsFile | No | Local file path containing a JSON array of field definitions | |
| isUnlocked | No | ||
| description | No | HTML content shown above the form | |
| introContent | No | Optional additional HTML intro | |
| requiredForCompletion | No | ||
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. | |
| allowExportBeforeComplete | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: partial update, version increment on field changes, archiving (not deletion) of removed field values. Lacks details on auth, rate limits, or error cases, but provides meaningful behavioral info beyond the no-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?
Two efficient sentences with no redundancy. First sentence states core purpose, second adds important behavioral detail about field updates. Front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers key parameter behaviors but lacks information about return values (no output schema), prerequisites (e.g., active site), and error conditions. Adequate but incomplete for a complex tool with 15 parameters.
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?
Adds meaning beyond schema for critical parameters: explains `fields` behavior (version increment, archiving), `siteId` (concurrent session context), and `confirmProductionWrite`. Schema coverage 67% is moderate, but description compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb (update), resource (workbook), and specifies partial update behavior. Distinguishes from other update tools by emphasizing that only provided fields change.
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?
No explicit when-to-use or comparisons to alternatives like thincms_create_workbook or thincms_get_workbook. Implies usage via partial update description, but lacks exclusions or scenario guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a file attachment to a lesson. Provide a local file path, a URL to download from, or base64-encoded content.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | URL to download and attach | |
| base64 | No | Base64-encoded file content | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| filePath | No | Local file path to upload | |
| filename | No | Filename (required for base64, optional otherwise) | |
| lessonId | Yes | Lesson ID (required) | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behaviors like permissions, file size limits, or side effects. It only states the action and input methods, lacking details on required authorization or potential conflicts.
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 very short (two sentences) and front-loads the purpose. While concise, it could include more detail without sacrificing brevity.
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 no output schema and 7 parameters, the description should mention required parameters, return values, or post-upload behavior. It omits that lessonId is required and does not explain what the agent receives after upload.
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 merely summarizes the input methods already detailed in the schema, adding no new semantics. It does not elaborate on parameter constraints or relationships.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Upload a file attachment to a lesson') and specifies the input methods (file path, URL, base64). However, it does not explicitly differentiate from sibling tools like thincms_upload_media, which uploads media generally.
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?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, scenarios where other tools are preferred, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload an image or file to the media library. Provide exactly one source: filePath (local file), url (download from URL), or base64 (encoded content with filename). For images, optimized WebP variants (thumbnail 400px, medium 800px, large 1200px) are automatically generated and returned in the variants field.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | URL to download and upload | |
| base64 | No | Base64-encoded file content | |
| siteId | No | Override the active site for this single call. Pass to target a specific tenant without mutating shared active-site state — the right pattern when running concurrent agent sessions managing different tenants. Must match a siteId from your THINCMS_SITES config (use thincms_list_sites to inspect). When omitted, the call uses the active site set by thincms_switch_site. | |
| altText | No | Alt text for accessibility | |
| caption | No | Image caption | |
| filePath | No | Absolute path to a local file | |
| filename | No | Filename (required for base64, optional otherwise) | |
| visibility | No | Visibility (default: public) | |
| confirmProductionWrite | No | Acknowledge that this call may write to a configured production site (THINCMS_PRODUCTION_SITE_IDS env var). Required for any POST/PUT/PATCH/DELETE against a production-listed site; ignored otherwise. The error message lists which site triggered the requirement and recommends thincms_snapshot before any production write. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden. It discloses automatic generation of WebP variants for images, which is valuable. However, it omits other behavioral details like file size limits, overwrite behavior, or required permissions, leaving gaps in transparency.
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 two sentences with no extraneous content. It front-loads the core action and then provides essential detail on source options and variant generation. Every word 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?
Given 9 parameters, no output schema, and no annotations, the description adequately covers the main function but lacks details on return format, error handling, prerequisites (e.g., site selection), and when to use confirmProductionWrite. It is complete enough for basic use but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by grouping sources as mutually exclusive and explaining the filename requirement for base64. It also provides context for siteId and confirmProductionWrite beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: uploading an image or file to the media library, with specific source options (filePath, url, base64). It distinguishes from sibling tools like thincms_list_media, thincms_get_media, etc., by focusing on the upload action.
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 implicitly guides usage by stating the three source alternatives, but it does not explicitly contrast with other upload tools like thincms_upload_lesson_attachment. No when-not-to-use or alternative recommendations are provided.
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.
v2.1.0thincms_add_quiz_questionthincms_add_sequence_stepthincms_analytics_referrersthincms_analytics_summarythincms_analytics_top_pagesthincms_analytics_trendthincms_append_cssthincms_bulk_create_poststhincms_campaign_statsthincms_capabilitiesthincms_clear_review_driftthincms_create_authorthincms_create_campaignthincms_create_categorythincms_create_collectionthincms_create_collection_itemthincms_create_content_blockthincms_create_coursethincms_create_enrollmentthincms_create_formthincms_create_integrationthincms_create_lead_magnetthincms_create_lessonthincms_create_modulethincms_create_pagethincms_create_popupthincms_create_postthincms_create_previewthincms_create_quizthincms_create_redirectthincms_create_scriptthincms_create_secretthincms_create_sequencethincms_create_tagthincms_create_toolthincms_create_workbookthincms_delete_authorthincms_delete_campaignthincms_delete_categorythincms_delete_collectionthincms_delete_collection_itemthincms_delete_content_blockthincms_delete_coursethincms_delete_enrollmentthincms_delete_lead_magnetthincms_delete_lessonthincms_delete_lesson_attachmentthincms_delete_mediathincms_delete_modulethincms_delete_pagethincms_delete_popupthincms_delete_postthincms_delete_quizthincms_delete_quiz_questionthincms_delete_redirectthincms_delete_sequencethincms_delete_sequence_stepthincms_delete_submissionthincms_delete_subscriberthincms_delete_tagthincms_delete_toolthincms_delete_tool_datathincms_delete_workbookthincms_export_course_portfoliothincms_export_submissions_csvthincms_export_subscribers_csvthincms_export_workbook_responsethincms_export_workbook_responses_csvthincms_generate_media_variantsthincms_get_campaignthincms_get_collectionthincms_get_content_blockthincms_get_coursethincms_get_formthincms_get_integrationthincms_get_lead_magnetthincms_get_lessonthincms_get_lesson_attachment_urlthincms_get_mediathincms_get_navigationthincms_get_pagethincms_get_popupthincms_get_postthincms_get_post_preview_urlthincms_get_preview_urlthincms_get_quizthincms_get_redirectthincms_get_reviewthincms_get_reviews_settingsthincms_get_sequencethincms_get_settingsthincms_get_share_buttonsthincms_get_social_linksthincms_get_tagthincms_get_templatethincms_get_toolthincms_get_tool_datathincms_get_workbookthincms_go_livethincms_import_redirectsthincms_list_authorsthincms_list_campaignsthincms_list_categoriesthincms_list_collection_itemsthincms_list_collectionsthincms_list_content_blocksthincms_list_coursesthincms_list_enrollmentsthincms_list_formsthincms_list_integration_liststhincms_list_integration_tagsthincms_list_lead_magnetsthincms_list_mediathincms_list_pagesthincms_list_popupsthincms_list_poststhincms_list_redirectsthincms_list_reviewsthincms_list_scriptsthincms_list_secretsthincms_list_sequencesthincms_list_sitesthincms_list_snapshotsthincms_list_submissionsthincms_list_subscribersthincms_list_tagsthincms_list_tool_datathincms_list_tool_end_usersthincms_list_toolsthincms_list_workbooksthincms_patch_cssthincms_pause_sequencethincms_publish_reviewthincms_publish_sequencethincms_re_analyze_review_sentimentthincms_reorder_collection_itemsthincms_reorder_module_itemsthincms_reorder_modulesthincms_reorder_sequence_stepsthincms_restore_snapshotthincms_searchthincms_send_campaignthincms_send_verify_emailthincms_seo_analyzethincms_seo_auditthincms_seo_check_linksthincms_set_review_editor_notesthincms_set_subscriber_passwordthincms_set_tool_datathincms_snapshotthincms_switch_sitethincms_sync_integrationthincms_sync_reviewsthincms_template_statusthincms_test_ai_connectionthincms_test_integrationthincms_unpublish_reviewthincms_update_authorthincms_update_campaignthincms_update_categorythincms_update_collectionthincms_update_collection_itemthincms_update_content_blockthincms_update_coursethincms_update_enrollmentthincms_update_formthincms_update_integrationthincms_update_lead_magnetthincms_update_lessonthincms_update_mediathincms_update_modulethincms_update_navigationthincms_update_pagethincms_update_popupthincms_update_postthincms_update_quizthincms_update_quiz_questionthincms_update_redirectthincms_update_reviews_settingsthincms_update_scriptthincms_update_sequencethincms_update_sequence_stepthincms_update_settingsthincms_update_share_buttonsthincms_update_social_linksthincms_update_tagthincms_update_templatethincms_update_toolthincms_update_workbookthincms_upload_lesson_attachmentthincms_upload_mediaScored across 191 tools
Most tools have distinct purposes, but with 191 tools, there is some overlap (e.g., thincms_get_post_preview_url vs thincms_create_preview both deal with previews, and multiple tools related to reviews and courses have similar boundaries). Some tools like thincms_bulk_create_posts could be confused with thincms_create_post.
All tools follow a thincms_verb_noun pattern, which is consistent. However, there are minor deviations: 'add' vs 'create' (thincms_add_quiz_question vs thincms_create_quiz), 'set' vs 'update', and some tools use 'get' vs 'list' inconsistently. Overall, the naming is predictable.
191 tools is far beyond typical MCP server sizes. While the server covers a broad CMS platform, this number will overwhelm agents and cause slow tool selection. A more focused set (e.g., 30-50 tools) would be more appropriate for the domain, with deeper nesting or sub-resources.
The tool surface is extensive, covering posts, pages, courses, quizzes, workbooks, emails, reviews, SEO, analytics, and integrations. However, some areas like user management (beyond subscribers) are limited, and there are no tools for comments or multi-user roles. The snapshot/restore feature is unique but incomplete for full CRUD on all resources.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server for building and testing AI agents with multi-model experimentation and insights.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
