thincms-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v2.1.0
Disambiguation3/5
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.
Naming Consistency4/5
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.
Tool Count2/5
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.
Completeness3/5
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.
Average 3.6/5 across 191 of 191 tools scored. Lowest: 2/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 5 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
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.
Conciseness2/5
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.
Completeness1/5
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.
Parameters1/5
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.
Purpose3/5
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.
Usage Guidelines2/5
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.
Behavior1/5
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.
Conciseness3/5
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.
Completeness1/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness2/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters2/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior1/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness3/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness3/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness3/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters2/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness3/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness3/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness3/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness3/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness3/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness3/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness2/5
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.
Parameters2/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness2/5
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.
Parameters4/5
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.
Purpose4/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness2/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description implies a read-only operation ('Get'), but does not explicitly state safety, idempotency, or potential side effects. It lacks details on whether the call requires a site to be active or how it behaves if navigation is empty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that directly state the tool's output and item structure. No unnecessary words, front-loaded with core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description explains basic output format, it does not specify the exact structure of the arrays (e.g., whether it's an object with 'header' and 'footer' keys). No mention of error conditions or empty states. Given no output schema, more detail would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for both parameters (siteId, confirmProductionWrite). The description adds no additional meaning or context for these parameters. Since schema coverage is high, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 'site's header and footer navigation arrays', and specifies the structure of each nav item (label, type, target). It distinguishes itself from sibling tools like thincms_update_navigation and other get tools by focusing on navigation arrays.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. It does not mention prerequisites (e.g., site must be active) or scenarios where it might not be appropriate. No comparison with similar get tools like thincms_get_page or thincms_get_settings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines4/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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 only mentions 'Only provided fields are changed,' indicating partial update, but lacks information on permissions, side effects, rate limits, or return behavior. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences are front-loaded with purpose and key behavior. No extraneous information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 4-param update tool with no output schema and no annotations, the description is adequate but minimal. It covers the basic purpose and partial update behavior. Could be improved by mentioning return value or error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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; it only restates the partial update nature. It does not explain parameter formats or constraints beyond what is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates share button configuration, specifies the context (blog posts, share via social platforms or copy link), and uses the verb 'update' with resource 'share button configuration'. It distinguishes itself from sibling 'thincms_get_share_buttons' by implying a write operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly provide when-to-use or when-not-to-use guidance. However, the name and context make it obvious this is for updating share buttons, and there is a read counterpart. No alternatives 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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness2/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness4/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness4/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully informs the agent about the return format (JSON with enabled and platforms) and lists possible platforms. However, it does not disclose any additional behavioral traits like caching, error states, or side effects, which are not expected for a GET operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise with only three sentences, all front-loaded with essential information: the action, resource, and return structure. Every sentence contributes value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a simple read tool with no output schema, the description adequately covers the return structure and platforms. However, it does not explicitly state that the configuration is fetched from the active site (unless overridden by siteId), which is context present in the schema but not integrated into the main description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 does not add any parameter-specific meaning beyond what is already in the schema. The schema descriptions for siteId and confirmProductionWrite are already detailed and self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('Get') and the resource ('share button configuration'), effectively distinguishing it from the sibling tool 'thincms_update_share_buttons' which performs a write operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
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. While the sibling update tool implies a read vs. write distinction, there is no direct 'when-to-use' or 'when-not-to-use' advice, leaving room for ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
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 full replacement behavior (implying destructiveness) and constraints on item types, but it does not mention side effects, authentication needs, rate limits, or what happens to existing navigation items. The description adds value but could be more explicit about 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences that front-load the core purpose and immediately clarify key constraints (full replacement, max 20 items, item types). Every sentence adds value with no wasted words, and the structure is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential aspects: what it does, the replacement nature, item types, and limits. It does not mention the siteId or confirmProductionWrite parameters, but those are well-described in the schema with 100% coverage. No output schema is needed since the operation's success is typically indicated by a status code. Overall, it is sufficiently complete for its purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 the schema by clarifying item types (e.g., 'page' requires a published slug, 'route' expects a CMS path) and providing examples. This helps the agent understand the valid values and constraints, enhancing usability beyond the raw schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates header and/or footer navigation, specifying it is a full replacement array with a maximum of 20 items. It distinguishes itself from siblings like thincms_get_navigation by explicitly describing the update action and the constraints on item types, making 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (to update navigation) and the nature of the operation (full replacement), but it does not explicitly state when not to use this tool or list alternatives such as thincms_get_navigation for reading. However, the context provided is sufficient for an agent to infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness4/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

thincms-mcp MCP server – quality and maintenance score on Glama

Copy to your README.md:

[![thincms-mcp MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/pmccarroll-fuel/thincms-mcp/badges/card.svg)](https://glama.ai/mcp/servers/pmccarroll-fuel/thincms-mcp)

Score Badge

Copy to your README.md:

[![thincms-mcp MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/pmccarroll-fuel/thincms-mcp/badges/score.svg)](https://glama.ai/mcp/servers/pmccarroll-fuel/thincms-mcp)