ClockNext MCP Server

Official

by ClockNext

Overview Schema Related Servers Score Discussions

TypeScript

Local

Server Quality Checklist

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

Latest release: v0.6.0
Disambiguation5/5
Every tool targets a distinct resource and action: CRUD per entity plus usage verification/recording and docs helpers. The verify vs record usage pair is clearly separated as dry-run vs billed, and all list/get/create/update/archive tools are unambiguous for their entity.
Naming Consistency5/5
All tools follow a consistent clocknext_verb_noun pattern in snake_case (list_models, create_credit, archive_unit, etc.). Even compound names like bulk_import_customers and whoami fit the general style without mixing conventions.
Tool Count2/5
35 tools is well above the 25+ threshold for 'too many', even though the billing domain has many entity types. The number feels heavy and could be trimmed or split into focused sub-servers, especially given several entities have near-identical CRUD patterns.
Completeness2/5
Significant lifecycle gaps exist: customers have no update/archive/delete, purchases have only create (no list/get/update/cancel), and there are no tools for invoices or wallet transactions. The core setup and usage recording flows work, but managing subscriptions and customers over time is incomplete.
Average 4.4/5 across 35 of 35 tools scored. Lowest: 3.8/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 30 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
This repository is licensed under MIT License.
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

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds that the response includes 'pricing, token mapping and active state', giving useful behavioral context about the return content. However, it does not disclose error handling or any additional side effects, though none are expected for a read 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 a single, well-structured sentence that front-loads the action and resource, then specifies the key returned fields. Every word earns its place and there is no wasted 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?
The tool has no output schema, so the description compensates by listing the content of the response (pricing, token mapping, active state). It gives a clear picture of what the caller can expect. It could be more complete by mentioning the response shape or potential errors, but for a simple get-by-id read operation, this 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 description coverage is 100% and the single parameter 'id' is documented as 'The credit id.' The description only reiterates 'by id' without adding extra semantic detail such as format, source, or validation rules. Thus the schema carries the weight, and the description adds marginal 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 uses a specific verb 'get' with a specific resource 'credit type' scoped by 'id', and explicitly lists the content returned: pricing, token mapping, and active state. This clearly distinguishes it from sibling tools like clocknext_list_credits (list all) and clocknext_get_customer (different resource).
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 its use case: retrieving a single credit type by ID, contrasting with listing all credits. However, it does not explicitly mention when to use this tool vs alternatives (e.g., clocknext_list_credits) or any prerequisites. The context is clear but without explicit 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 contradicts the annotation destructiveHint: true by claiming 'NOT a delete', that it's reversible, and that customers are unaffected. This is a serious inconsistency that could mislead an agent about the tool's destructive potential.
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 and front-loaded with the core action. Each subsequent sentence adds necessary context about consequences, reversibility, and exclusions without redundancy or wasted words.
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 one-parameter tool with no output schema, the description is exceptionally complete. It covers the operation's effect (sets isActive to false), side effects (history kept, customers unaffected), reversibility, and usage limits. The annotation contradiction is separate and does not reduce the textual 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 schema already provides 100% coverage for the single parameter, describing it as 'The plan id to deactivate (soft-archive — reversible, not a delete).' The description's mention of soft-archive and reversibility merely mirrors the schema, adding no new parameter-specific 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 opens with a specific verb ('Deactivate'), names the resource ('plan in your catalogue'), and explicitly contrasts with 'NOT a delete', making its purpose unmistakable. It distinguishes itself from other archive tools and from deletion operations.
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 gives explicit when-to-use guidance ('Use ONLY to retire a plan you no longer sell'), clarifies what it is not for ('unrelated to cancelling a customer's purchase or ending a subscription'), and names the alternative for reactivation (clocknext_update_plan).
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 already declare readOnlyHint=true and openWorldHint=true. The description 'Fetch one customer' is consistent but adds no extra behavioral context beyond what the schema (parameter id) implies. It does not disclose behavior for non-existent ids or return format. Given annotations cover the safety profile, this is acceptable but not enriched.
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, short sentence of six words. Every word is informative, with no filler or repetition. It is perfectly 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?
For a simple get-by-id operation with one parameter and no output schema, the description covers the essential purpose. It does not explicitly state what is returned (e.g., the full customer object), but this is largely implied by the operation name and field. It is sufficiently complete for an agent to invoke correctly, though a touch more detail on return behavior would make it a 5.
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 the parameter id described as 'The ClockNext customer id.' The description repeats this by saying 'by ClockNext id' without adding new meaning. Baseline 3 is appropriate since the schema fully documents the parameter and the description provides no 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?
The description uses a specific verb 'fetch' and identifies the resource 'customer' plus the selection mechanism 'by ClockNext id.' This clearly distinguishes it from siblings like list_customers or create_customer, so 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates when to use the tool: when retrieving one specific customer by its ClockNext id. It does not explicitly mention alternatives like list_customers, but the context of 'one customer by id' implies a targeted lookup, making the usage context clear without 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?
Annotations already declare readOnlyHint=true, so the description need not restate safety. It adds useful context that the plan is 'current active' and 'from their purchase,' revealing its dependency on purchase state. However, it does not disclose edge-case behavior (e.g., what happens if no active plan exists), and with openWorldHint true, behavior may vary. This is acceptable 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 exactly two sentences: the first states the core function, the second provides a practical use case. It is front-loaded with the action and resource, and every word adds value. No redundant or fluff 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?
Given the tool's simplicity (one parameter, no output schema, read-only annotation), the description covers the essential aspects: what it does and when to use it. It does not explain the return format or edge cases, but the readOnlyHint and openWorldHint annotations help mitigate the need. The description is adequately complete for an agent to select and invoke 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?
The input schema fully describes the single parameter 'id' as 'The ClockNext customer id.' The description adds only the word 'customer' in context, not additional meaning such as format, constraints, or usage examples. Since schema coverage is 100%, a baseline score of 3 is appropriate, and the description does not compensate beyond that.
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 function: 'Fetch a customer's current active plan (from their purchase).' It uses a specific verb and resource, and it distinguishes this from sibling tools like get_customer and get_plan by focusing on the customer's active plan. The additional use-case context ('confirm a customer is subscribed to the plan you expect') further clarifies its unique role.
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 when-to-use scenario: 'Use it to confirm a customer is subscribed to the plan you expect before firing a test signal.' This offers clear guidance for appropriate use, though it does not explicitly mention alternatives or exclusion cases. The context is sufficient for most agents to differentiate it from related 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?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering safety. The description adds meaningful context about the response contents ('full' plan with entitlement components, billing cycle, currency, active state), which goes beyond the annotation. However, it does not disclose error behavior (e.g., missing ID) or other edge cases.
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, front-loaded sentence efficiently conveys the action and scope. The em-dash list of components is concise and structured, with no redundant 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?
With one parameter, no output schema, and read-only annotations, the description still lists the return fields (entitlement components, billing cycle, currency, active state), which compensates for the lack of an output schema. It is complete for a simple get-by-id tool, though it omits error case 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?
Schema coverage is 100% — the only parameter 'id' is described as 'The plan id.' The description merely repeats 'by id' without adding additional semantics, so it matches the baseline for comprehensive 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 uses a specific verb ('Get') and resource ('one plan') with clear scope ('in full'). It itemizes the components (wallet/credit/outcome/unit/flat, billing cycle, currency, active state), which clearly distinguishes it from siblings like list_plans or create_plan.
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 retrieving a single plan by ID, but does not explicitly contrast with list_plans (for multiple plans) or get_customer_plan (for a customer's plan). No when-not-to-use guidance is provided.
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?
Annotations already declare readOnlyHint=true, so the description correctly aligns with a read operation. It adds value beyond the annotation by disclosing what 'in full' includes: 'pricing type, flat price or tiers, plus usage stats', which informs the agent about the return payload—important since there is no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that leads with the verb and resource, immediately followed by what is returned. Every word earns its place, with no redundant or filler 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?
Given the tool's simplicity (one required parameter, no output schema, annotations present), the description adequately covers the action and return contents. It could be slightly more complete by mentioning that this only retrieves one unit type and not related entities, but for a straightforward get, it 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 covers the only parameter 'id' with a description ('The unit id.'). The tool description simply says 'by id', which adds no additional meaning beyond the schema. Schema coverage is 100%, so the baseline of 3 applies; no extra parameter syntax or constraints are provided.
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 one unit type in full by id', specifying the exact verb, resource, and scope. It distinguishes itself from sibling 'list_units' (which lists all) and other 'get_*' tools for different entities by naming 'unit type' and enumerating the returned contents.
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 (when you need full unit type details by id) but does not explicitly mention exclusions or alternatives. It lacks guidance such as 'use list_units to browse' or 'see get_plan for plans', so 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds the return fields and a use case but no additional behavioral traits such as pagination, ordering, or permission requirements. It does not contradict the annotations.
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 action and scope. The first sentence states exactly what the tool does, and the second gives a practical use case. No redundant or irrelevant words.
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?
This is a simple read-only list tool with one optional parameter. The description covers the return fields, the purpose, and a concrete use case. Combined with the annotations and full schema coverage, it provides all necessary context for an agent to select and invoke 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%, and the sole parameter 'active' is fully documented with its meaning ('Only return active credits when true; omit to return all'). The description adds no extra parameter-specific semantics beyond listing the resource, so the 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 'List' with a clear resource ('the organisation's credit types') and enumerates the fields returned. It distinguishes itself from sibling tools like get_credit (singular fetch) and create/update/archive by focusing on listing. The added use case for finding a credit id to reference in a plan's CREDIT component further sharpens 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 explicitly provides a usage context: 'Use it to find a credit id to reference from a plan's CREDIT component.' This gives clear guidance on when to invoke the tool, but it does not mention alternatives or when not to use it (e.g., when needing a single credit, use get_credit).
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 already declare readOnlyHint and openWorldHint, and the description does not contradict them. It adds some context by naming the returned fields and the intended use case, but does not disclose additional behavioral details such as pagination, sorting, or auth requirements. With annotations covering the safety profile, 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?
Two concise sentences, with the core function in the first sentence and a clear use case in the second. No filler or redundant information, and the most important information is front-loaded.
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 list tool with one optional parameter and no output schema, the description is complete: it states the resource, the returned fields, and the primary use case. The annotations provide safety context, and nothing critical is missing.
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 for the only parameter ('active'), so the description does not need to explain it. The description mentions 'active' as an output field, which is slightly related but does not add parameter-specific meaning beyond 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 tool lists the organisation's unit types and enumerates the returned fields (id, name, pricing type, active). The explicit use case of finding a unit id to reference in a plan's UNIT component further clarifies its purpose and differentiates it from sibling 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear when-to-use directive: 'Use it to find a unit id to reference from a plan's UNIT component.' It does not explicitly mention when not to use it or name alternatives, but the stated use case provides sufficient 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?
Beyond the annotations (readOnlyHint=false, idempotentHint=false), the description adds valuable behavioral detail: the batch returns a per-row result with either a created id or an error, and one bad row never aborts the batch. It also discloses that this is a private MCP-only endpoint. This is significant context not inferable from the annotations or 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 concise and front-loaded, with the core purpose in the first clause. It packs essential information (batch behavior, per-row results, size limit, chunking) into a few dense sentences without wordiness or repetition. Every sentence contributes unique 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 bulk import tool with a single array parameter and no output schema, the description covers the key operational aspects: required fields, max batch size, per-row results, error handling, and how to scale. It does not provide an exact response schema, but the description's logical model of per-row results is sufficient for an agent to understand what to expect.
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 that each customer needs name + email and the 200-per-call limit, but both are already in the schema (required fields and maxItems). The 'match back by email' note adds context but is also hinted in the email field description. No negative impact, but 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 opens with 'Bulk-create ClockNext customers in ONE request', which states the exact action (bulk create), resource (ClockNext customers), and scope (multiple in one request). It also mentions 'backfilling an existing user base', clearly positioning it relative to single-customer creation tools like create_customer.
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 usage context: it is for backfilling an existing user base and uses a private bulk endpoint. It also gives chunking advice for larger bases. However, it does not explicitly contrast with the single-create sibling (create_customer) or mention scenarios where bulk import is inappropriate, so it stops short of full 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?
The description discloses that the tool returns the customer with its ClockNext id, clarifies that only name and email are required while all other fields are optional profile, and explains how the returned id is used downstream. This adds behavioral context beyond the annotations (readOnlyHint=false, idempotentHint=false) without contradicting them.
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 text. It front-loads the core operation ('Create a ClockNext customer'), states required fields, and ends with the crucial downstream usage of the returned id. Every clause 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?
Despite 16 parameters and no output schema, the description covers the essential context: what a customer is, required vs optional fields, and the return value's role in subsequent operations. It could have detailed the response structure further, but the description is sufficient for an agent to correctly 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?
The description groups all non-required fields as 'optional profile,' providing some semantic context, but does not elaborate beyond what the schema already states. With schema coverage at only 38%, this grouping partially compensates, but individual parameters like city, phone, and taxId are left to their self-explanatory names. It adds minimal value over the schema's required/optional distinctions.
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 a ClockNext customer and defines it as the billing entity mapping to end-users/tenants/organizations. This specific verb+resource pairing, along with the billing context, distinguishes it from sibling tools like clocknext_list_customers or clocknext_bulk_import_customers.
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 explains that the created customer's id is required for subscribing to a plan (clocknext_create_purchase) and recording usage (clocknext_record_usage), clearly implying when to use this tool. It does not explicitly name alternatives or exclusions, but the creation verb and downstream references provide clear usage context.
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?
Annotations already indicate a non-read-only (readOnlyHint=false) and non-idempotent (idempotentHint=false) operation. The description adds behavioral context by explaining that the plan becomes active and that usage signals only price when an active plan's components match the meter. This goes beyond the annotations, though it doesn't discuss side effects like billing or return values.
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 core action, and includes both purpose and context without any redundant wording. 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?
Given the tool's complexity (6 params, 2 required), the schema fully documents parameters, and the description provides clear purpose, prerequisites, and a use case. The only gap is that no output schema exists and the description does not mention return values, but for a mutating subscription tool, this is a minor omission.
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 for parameters is 100%, meaning all six parameters have descriptions in the input schema. The description itself does not add parameter-specific semantics, but it does mention the concept of 'active plan' indirectly. Since the schema covers parameters thoroughly, the 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 verb and resource: 'Subscribe a customer to a plan', and elaborates that this is a purchase that activates the plan. It distinguishes from sibling tools like clocknext_create_plan and clocknext_create_customer by specifying the action is about subscription/activation, not creation of entities.
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 explicit sequencing: 'do this after clocknext_create_customer + clocknext_create_plan' and a concrete use case: 'wire up a dummy customer before firing test signals'. However, it does not explicitly mention when not to use this tool or list alternative tools, which prevents a perfect score.
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?
Annotations already declare readOnlyHint=true, and the description adds behavioral context about what is returned (steps and stats). This goes beyond the annotations by clarifying the response content, though it doesn't describe pagination or 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?
The description is a single, front-loaded sentence that conveys all essential information without unnecessary words or repetition. 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?
For a simple get-by-id tool with one parameter and no output schema, the description provides sufficient context about the return value (steps and stats) to orient the agent. It could be more explicit about the format of stats, but overall it's complete 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% with a clear description for the 'id' parameter. The tool description adds no additional meaning beyond 'by id', which is already implied by the parameter name and 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 gets 'one outcome type in full by id' with specific content ('steps plus in-flight/completed stats'). This distinguishes it from sibling tools like clocknext_list_outcomes, which presumably list multiple outcomes without full detail.
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 use for a single outcome type by id, contrasting with list operations. It provides clear context for when to use the tool, though it doesn't explicitly name alternatives or exclusion scenarios.
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?
Beyond the readOnlyHint annotation, the description adds meaningful behavioral details: results are ordered most-recent first and are cursor-paginated. This discloses pagination and ordering behavior that annotations do not cover. The description is consistent with annotations; no contradiction.
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 core action, and each sentence carries purpose or usage guidance. No wasted words or repetition of schema 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 read-only list/search tool with three optional params and no output schema, the description adequately covers behavior (ordering, pagination) and use case. It could mention what fields are returned or that pagination uses a nextCursor, but the overall context is complete for typical 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 description coverage is 100%, so the schema already explains all three parameters (q, limit, cursor). The description's mention of 'search' and 'cursor-paginated' slightly reinforces the schema but adds no new semantic 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 a specific action ('List / search the org's customers') with resource and scope, and adds the distinguishing purpose of finding a customer ID or checking existence before creation. This differentiates it from siblings like get_customer (single fetch) and create_customer.
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 use-case guidance ('Use it to find a customer id or check whether one already exists before creating'), indicating when this tool is appropriate. It does not explicitly name alternatives or exclusions, but the context is sufficiently clear for an agent to choose it over related 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?
With no annotations provided, the description carries the full transparency burden. It discloses that the tool lists only enabled models, includes prices, returns modelId for downstream use, and supports an active filter. While it does not mention pagination or output format, it adds meaningful behavioral detail beyond the bare 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?
Three concise, front-loaded sentences: purpose, downstream usage hint, and parameter guidance. Every sentence adds value, with no redundant or filler 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?
Given the tool's simplicity (one optional boolean parameter, no output schema), the description covers the essential aspects: what is listed, pricing, modelId usage, and the active filter. It lacks details on response structure or pagination, but these are not critical for this 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?
The schema already fully documents the single parameter `active` with 'Only return currently-active (meterable) models.' The description's 'Pass active=true to see only models that can be metered right now' adds minimal extra context ('right now'), so it does not significantly enhance 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 tool lists enabled models with their USD pricing per million tokens, using a specific verb ('List') and resource ('models'). It distinguishes itself from sibling list tools by focusing on models and their prices, and ties the returned modelId to usage in verification/recording.
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: use the returned modelId for verifying or recording usage, and optionally pass active=true to filter for currently meterable models. It does not explicitly mention when not to use it, but the guidance is sufficient for the user to understand the tool's role.
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?
Annotations already indicate a write operation (readOnlyHint=false) and non-idempotency. The description adds that this creates a 'real, sellable plan' and warns to verify pricing, which is meaningful behavioral context beyond the flags. No contradiction.
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 dense but each sentence conveys distinct information: component types, billing modes, FREE special case, dashboard preference, and pricing warning. Structure is logical, though slightly long.
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 prerequisites, special-case rules, and usage guidance effectively. It does not discuss return values or error behavior, but given no output schema and rich parameter descriptions, it is adequately complete 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%, with detailed param descriptions. The description mostly restates component and billingMode rules (WALLET, FLAT, ADVANCE/ARREAR, FREE constraint) that are already in the schema, adding little new semantic 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 opens with 'Create a billing plan' and clearly elaborates that a plan bundles entitlement components (WALLET, FLAT, CREDIT, etc.), distinguishing it from sibling create tools like clocknext_create_credit/outcome/unit. It also positions itself as a fallback to the dashboard builder, clarifying its unique role.
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?
Explicitly states to prefer the dashboard plan builder and use this tool as a fallback. It also instructs users to create referenced components first (clocknext_create_credit / _outcome / _unit) and list them to get IDs, which is concrete when-to-use 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?
Annotations already declare readOnlyHint=true and openWorldHint=true; description adds that it returns current balances across wallet/credit/outcome/unit and frames read-only verification scenarios. No contradiction with annotations, and the added domain context is useful.
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; first states action and object, second gives practical use cases. No filler.
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 one-parameter read tool, the description covers what data is returned, why to use it, and read-only nature; annotations cover safety. No output schema is necessary because the description names the balance categories.
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 has 100% coverage with a single 'id' parameter described as 'The ClockNext customer id.' Description doesn't add parameter-level detail, but schema is sufficient; 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 specific verb 'Fetch' and identifies resource 'customer's current wallet / credit / outcome / unit balances.' It clearly differentiates from siblings like clocknext_get_customer_usage or clocknext_get_customer_plan by specifying balance 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?
States explicit use cases: confirming a purchase granted expected entitlements, and verifying a test signal drew down balances. This gives clear context for when to invoke, though it doesn't mention exclusions or 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?
Annotations already indicate readOnlyHint and openWorldHint. The description adds that the tool returns a list of outcome types with specific fields and serves a lookup purpose, which is beyond just the annotation's safety signal. It doesn't disclose pagination or authentication, but does add some 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 two sentences: one for the action and return fields, one for the use case. No filler words; every sentence serves a purpose.
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 simple tool with one optional parameter, no output schema, and read-only annotation, the description covers the return fields and the primary use case. It does not mention pagination or sorting, but for a low-complexity list operation, this 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?
Schema coverage is 100% for the single 'active' parameter, which is fully described in the schema as 'Only return active outcomes when true; omit to return all.' The description does not add parameter-level details, 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 clearly states the verb 'List' and the resource 'outcome types', and enumerates the returned fields (id, name, price, active). It also distinguishes from sibling tools like clocknext_get_outcome by framing it as the way to find an outcome id for a plan's OUTCOME component.
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 an explicit use case: finding an outcome id to reference from a plan's OUTCOME component. While it doesn't name alternatives, the context implies this is the list tool for outcomes, leaving get/create/update/archive for other operations.
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?
Beyond the readOnlyHint and openWorldHint annotations, the description adds meaningful context: 'only sellable plans' implies business logic for the active filter, and listing the output fields (id, name, billing cycle, price, active) is valuable given there is no output schema. It aligns with annotations and adds behavioral nuance.
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 with no filler. The first sentence front-loads the purpose, the second gives use cases, and the third adds a filter hint. Every sentence earns its place.
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 list tool with one optional parameter, the description fully covers the purpose, output fields, and an important filter behavior. Combined with the annotations and schema, it is complete and unambiguous.
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 already provides 100% coverage for the 'active' parameter, so this is the baseline. The description adds the business term 'sellable' but otherwise doesn't introduce syntax or semantics beyond what the schema describes.
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 ('organisation's billing plans'), enumerates the returned fields, and specifies a concrete use case ('find a plan id or see what's on offer'). This distinguishes it from sibling tools like get_plan, which retrieves a single plan.
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 use cases: 'find a plan id or see what's on offer' and gives a conditional modifier ('Pass active=true for only sellable plans'). However, it does not reference alternatives such as get_plan for single-plan lookups or state explicit exclusions, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true and openWorldHint=true, and the description adds useful context: logs are returned most recent first, and you can check for expected model, tokens, and cost. It doesn't describe edge cases like missing IDs, but for a read-only tool 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?
Three sentences, front-loaded with the core purpose. Each sentence adds distinct value: what it does, when to use it, and how it differs from a sibling. No fluff or repetition.
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 read tool with two well-documented parameters and no output schema, the description explains the use case, the expected content of the logs, and the alternative. It could mention default limit behavior or empty results, but overall it is complete enough for an agent to select and invoke 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 descriptions already cover both parameters 100% (customer id and limit). The description repeats 'most recent first' and adds value by explaining what the logs contain (model, tokens, cost), but it doesn't add new parameter-level meaning beyond what the 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?
Description clearly states the verb ('Read back') and resource ('a customer's recent usage logs'), with ordering ('most recent first'). It also differentiates from sibling clocknext_record_usage by explaining this tool is for confirming signals from the running codebase, not for directly fired signals.
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?
Explicitly says when to use: to CONFIRM a signal landed after running the product's code. It also names the alternative (clocknext_record_usage) and explains why this tool is mainly for signals sent by the running codebase, giving clear when/when-not guidance.
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 carries the behavioral disclosure burden. It clearly states side effects (or lack thereof): 'Records nothing and never bills.' It also reveals the return behavior: 'Returns the projected usage log (cost, credits drawn, applied rules).' This gives the agent confidence that the operation is safe and non-mutating, which is critical for a dry-run 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 two sentences, front-loaded with the essential 'dry run' concept, and every clause earns its place. It packs purpose, behavioral guarantees, and return value into a compact, scannable format without wordiness 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?
Despite having no output schema, the description supplies a clear summary of the return value: 'projected usage log (cost, credits drawn, applied rules).' It also gives the usage context (pre-traffic validation). It does not detail error cases (e.g., invalid customer ID) or explain the 'plan' wiring context, but for a selection/invocation task the description is nearly complete. A slightly richer error-behavior note would earn a 5.
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 provides exhaustive descriptions for all 8 parameters (100% coverage), including enums, defaults, and semantics. The description adds only a general reference to 'customer, model, and plan' but does not elaborate on parameter formats or interplay. Thus the schema does the heavy lifting, and the description meets the baseline without adding significant extra 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 opens with a precise verb-phrase: 'Validate and PRICE a usage signal WITHOUT recording it — a dry run.' It clearly identifies the tool's function (dry-run validation/pricing) and resource (usage signal), and implicitly distinguishes it from the sibling recording tool (clocknext_record_usage) by emphasizing that it records nothing. This unambiguous purpose leaves no room for confusion.
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 when to use the tool: 'so you can confirm the customer, model, and plan are wired up correctly before sending real traffic.' It implies using this before clocknext_record_usage. However, it does not explicitly name the alternative tool or provide exclusion criteria (e.g., 'do not use for actual recordings'), so it falls just short of a full 5.
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?
Annotations already mark this as a write operation (readOnlyHint=false), and the description aligns with that. It adds valuable behavioral context beyond the schema: the agentKey is a durable identity unique org-wide, and a rename never changes it. It also discloses tier constraints (1–50, ordered, only last may be null). It doesn't cover failure modes, but given annotation coverage, this is a solid enhancement.
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 dense paragraph, but it follows a logical order: definition, pricing options, tier constraints, dashboard fallback, plan relationship. Some details duplicate schema (e.g., tier null rule), but there is no filler. It could be improved with line breaks or bullet points, but it remains focused and readable.
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 create tool with 7 parameters and no output schema, the description covers the domain thoroughly: what a unit is, when to use it, pricing models, tier rules, and how plans consume the unit. The only notable gap is not describing the return value or success/error behavior, which would be more critical in the absence of an output schema. Overall, it's nearly 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?
Schema coverage is 100%, so the baseline is 3. The description adds conceptual meaning for all parameters: it explains that agentKey is the durable reported identity, flatPrice defaults to 0 and is for FLAT pricing, pricingType distinguishes FLAT vs tiered models, and tiers have ordering/null-bound rules. This enriches the raw schema definitions with domain context.
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 opens with 'Create a unit type' — a specific verb and resource — and immediately defines what a unit is (a metered usage unit with a durable agentKey). It explicitly distinguishes this from sibling create_* tools by scoping to fixed-cost/non-LLM events and explaining how plans reference units. This is a clear, non-tautological purpose statement.
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 gives explicit usage guidance: 'PREFER the dashboard... use this tool as the fallback.' It also provides domain rules (units are for fixed-cost/non-LLM events, one event = one unit) and a prerequisite relationship ('A plan meters it via a UNIT component'). This goes beyond generic context to actionable when-to-use/fallback 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 carries the full burden. It discloses the key behavioral outcome: returning the organization identity and sandbox/live status. It also adds safety context about verifying the workspace before real usage. However, it does not detail the exact response structure or any potential side effects, though for a read-only identity check 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 two sentences long, front-loads the core purpose, then adds the critical sandbox/live distinction, and ends with actionable usage guidance. Every sentence adds value with no redundancy or filler.
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, zero-parameter identity-check tool with no output schema, the description is fully complete. It explains what the tool does, what it returns (org identity and sandbox/live status), and when to invoke it. No other information is necessary for the agent to use it 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?
The tool has zero parameters and the schema is empty, so the baseline is 4. The description does not need to explain parameters, and it appropriately omits any parameter details. There is nothing missing here.
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 function: 'Identify the ClockNext organisation behind the configured API key' with the critical distinction of sandbox vs. live. This is a specific verb+resource+scope that differentiates it from sibling tools, which focus on other operations like listing models, recording usage, or managing customers.
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 explicit usage context: 'Call this FIRST to confirm you are pointed at the intended workspace before recording any real usage.' This clearly indicates when to use it (as a preliminary verification step) but does not mention when not to use it or name alternative tools.
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?
The description goes beyond annotations by detailing the soft-archive behavior: keeps credit/history, existing plans keep working, new plans cannot add it, it drops from active lists, and is reversible. Even though destructiveHint=true exists, the description clarifies the operation is non-destructive and reversible, providing context annotations alone could not convey.
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 fairly long but every sentence earns its place: action, effects, reversibility, usage scope, and explicit non-goals. It is front-loaded with the core action. Slight verbosity could be trimmed, but the structure is logical and dense with useful 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?
For a single-parameter tool with no output schema, the description fully covers behavior, side effects, reversibility, and exclusions. It also cross-references related tools (update_plan, update_credit) for follow-up actions, making the tool context complete enough for an agent to use 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?
The schema description already states the parameter id is 'The credit id to deactivate (soft-archive — reversible, not a delete).' The description repeats this but adds no new literal meaning beyond emphasizing reversibility and non-deletion. With 100% schema coverage, the prose adds minimal additional parameter-level 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 immediately identifies the tool as deactivating a credit TYPE (sets isActive→false), clearly distinguishing it from a delete and from other archive tools (e.g., archive_plan, archive_customer). It names the exact verb and resource, and explicitly states what it does not do, leaving 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit use context: 'Use ONLY to retire a credit you no longer sell.' It also lists exclusions and alternatives: update_plan to stop offering on plans, update_credit to reactivate, and clarifies it is unrelated to archiving customers/ending purchases/clearing balances. This is exemplary guidance for when and 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, idempotentHint=false), the description discloses important behavioral details: the tool reads live model prices, computes base price and price-per-credit automatically, and stores only the computed price. It does not contradict the annotations, though it omits detailed error or duplicate-handling behavior.
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 opens with a strong one-sentence purpose and remains readable, but it is somewhat long with multiple asides (dashboard alternative, plan granting). Every sentence adds value, though a tighter version would be even more concise.
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, lack of output schema, and annotations that already flag write behavior, the description is remarkably complete. It covers purpose, prerequisites, pricing computation, alternatives, and downstream plan usage, giving an agent everything needed to invoke it 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?
The schema already covers 100% of parameters with rich descriptions, so the baseline is 3. The description adds extra algorithmic meaning by explaining how models and marginPercent combine for model-grounded pricing and why agentKey is durable, which goes beyond simple field 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 it creates a credit type (a token-metered entitlement) with specific verb and resource. It distinguishes itself from sibling tools such as get/update/archive/list credits and create_plan by describing its unique role in the system.
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 explicitly names the dashboard as the first-class alternative and labels this tool as the fallback. It also gives prerequisites like using enabled catalog models from clocknext_list_models and mentions how the credit is granted via a plan, making when-to-use guidance 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?
Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false), the description discloses the pricing computation: base costs from live model prices, summing steps, and applying marginPercent. It also adds constraints like 1–50 steps and enabled models. It doesn't discuss error behavior or duplicate handling, but this goes well beyond what annotations provide.
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 moderately sized but every sentence earns its place: defining the tool, explaining pricing mechanics, contrasting with units, and giving an alternative. It is front-loaded with the core purpose and progressively adds context, though it could be slightly tightened.
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 multi-step create tool with rich schema and no output schema, the description covers the essential context: what an outcome is, pricing calculation, step/model requirements, the unit distinction, dashboard alternative, and plan granting. This is sufficient for an agent to decide and invoke the tool 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 the baseline is 3. The description adds meaning by explaining how `steps` map to per-step `agentKey` and `models`, and that `marginPercent` is applied to the summed base cost. It also clarifies that each step is an LLM step and non-LLM fixed-cost events belong in units.
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 a specific verb+resource: 'Create an outcome type' and clearly defines it as 'a multi-step LLM deliverable billed per COMPLETED outcome.' It also distinguishes this tool from siblings by contrasting outcomes with units and referencing the dashboard alternative, so it 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: outcomes are for 'token-priced, multi-LLM-step deliverables' while 'a fixed-cost / non-LLM event ... belongs in a UNIT.' It also names an alternative workflow ('build it in the dashboard') and notes the tool is a fallback, plus how plans grant access via an OUTCOME component.
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 clearly indicates this is a read operation, returns authoritative page content 'verbatim', and explicitly warns that external fetches may 'silently drop details.' It doesn't mention errors or rate limits, but for a read-only docs tool, the key behaviors are well disclosed.
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 front-loaded with the core purpose, and each paragraph adds useful guidance. It is longer than strictly necessary, with some repetition (e.g., 'read the whole page' and 'read THAT page in full'), but every sentence contributes to clarity and safe usage.
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 (one required parameter) and the absence of an output schema, the description fully compensates by specifying the Markdown return format, the type of content included, and how to obtain the input. It is complete for the intended workflow.
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 already covers the single `path` parameter (100% coverage), but the description adds important semantics by explaining the parameter comes from a clocknext_search_docs result and providing valid example values like 'https://help.clocknext.com/docs/sdk/signals'.
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 function: 'Read the FULL contents of a single ClockNext docs page as Markdown.' It identifies the specific resource (docs page) and action (read) and explicitly distinguishes itself from its sibling clocknext_search_docs, which only returns snippets.
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 gives explicit when-to-use guidance: 'Use this right after clocknext_search_docs: pass the url of a promising search result.' It also names the alternative to avoid (external web-fetch/browser tools) and explains why, making the usage decision 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?
Annotations provide openWorldHint=true and idempotentHint=false, but the description adds important context: the operation is metered and billed, it prices tokens against the plan, and it returns the resulting usage log. It also clarifies the idempotency behavior when using idempotencyKey (repeat returns original result), which goes beyond the bare hint. Minor omissions like auth requirements are not disclosed, but the financial and retry behavior is well covered.
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, front-loaded with the most critical warning (metered and billed), then explains the pricing/return behavior, then provides retry guidance and an alternative. Every sentence carries essential information with no filler 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?
Given nine parameters, no output schema, and only two annotations, the description covers the key contextual aspects: the financial consequence, the return value (usage log), idempotency behavior, and a clear alternative tool. It does not describe error scenarios or the structure of the returned usage log, but for the agent's selection and invocation needs it is largely sufficient. A 5 would require more detail about failure modes or output shape.
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 beyond the schema by explaining the overall pricing behavior and specifically the semantics of idempotencyKey: reusing the same key across retries prevents double-recording and returns the original result. This enriches the parameter understanding even though individual parameter descriptions are already exhaustive 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 opens with a specific verb and resource: 'Record ONE real usage signal — it is metered and billed.' It clearly distinguishes the tool from the sibling clocknext_verify_signal by contrasting a real metered record with a no-op preflight, and it states what the tool does (prices tokens, returns a usage log). This is precise 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent when to use this tool versus the alternative: 'For a no-op preflight, use clocknext_verify_signal instead.' It also sets expectations that this action is metered and billed, implying it should be used only for actual usage recording, and gives clear guidance about retries with idempotencyKey. This exceeds the baseline with a direct exclusion.
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 of behavioral disclosure. It reveals that the tool searches across kinds, returns snippets, and works through concept/api/javascript in order. It also surfaces a critical non-obvious behavior: the docs will not tell you the SDK is JS/TS only, so the tool description compensates for that gap. It does not describe exact return formatting or pagination, but the essentials are covered.
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 lengthy but well-structured with numbered list and bolded key points. Each section adds distinct value: the SDK caveat, the kind ordering, and the typical flow. It is not overly verbose; every sentence contributes to correct tool usage, though it could be trimmed slightly without losing critical 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 moderate complexity (three kinds, SDK restriction, integration scenarios), the description is fully complete. It explains what the tool returns (title, URL, snippet), how to sequence searches, and how to handle non-JS/TS cases. No output schema exists, but the description explicitly states return fields, so the agent knows what to expect.
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 the baseline is 3. The description adds meaningful guidance above the schema: it explains the meaning and order of the 'kind' values, clarifies that 'javascript' is only for JS/TS codebases, and provides real-world examples for 'query'. This goes beyond the generic property 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 function: searching ClockNext's official documentation and returning the most relevant pages with title, URL, and snippet. It distinguishes itself from sibling tools by emphasizing it is the docs search tool, while other siblings like clocknext_get_doc likely retrieve a specific document. The verb 'search' and specific resource 'docs' are explicit.
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?
Provides explicit when-to-use guidance: 'ALWAYS prefer this over answering from memory' and instructs to call it before explaining concepts or designing integrations. It also gives exclusions by telling users not to use the 'javascript' kind for non-JS/TS codebases, with an alternative ('use api'). It outlines a typical search flow, making alternatives and sequencing clear.
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?
Beyond the annotations, the description discloses destructive semantics: omitted fields are cleared, pricing is re-grounded, and changing agentKey re-points runtime signals. This is exactly the kind of behavioral context annotations do not provide, and it does not contradict readOnlyHint/idempotentHint.
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 front-load the most important fact (full rewrite, not patch), then add prerequisites and cautions without redundancy. Every sentence carries operational 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 7-parameter mutation with no output schema, the description covers destructive behavior, prerequisite reads, pricing behavior, and the agentKey risk. It loses a point because the isActive advice conflicts with the closed input schema and the return/result shape is not mentioned, but overall it is unusually thorough.
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, so baseline is 3. The description adds meaning by explaining the models mixer re-grounds pricing and that agentKey is the durable identity whose change deliberately re-points signals. However, it references 'isActive' which is not present in the schema, slightly muddying parameter guidance.
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 opens with 'Replace a credit by id with its COMPLETE new definition', giving a specific verb and resource and distinguishing it from a partial patch. It also notes pricing is re-grounded 'same as create', which orients it among create/update/archive siblings.
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 gives an explicit prerequisite: read the current credit with clocknext_get_credit first. It also gives a concrete use case for toggling active state. It does not name alternative tools to avoid, but the full-rewrite framing makes the update-vs-create distinction clear.
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?
Annotations already indicate readOnlyHint=false and idempotentHint=true. The description adds the critical behavioral trait that omitted optional fields are CLEARED, not preserved, and that changing agentKey re-points signals — important context beyond the annotations. No contradiction.
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, front-loaded with the key concept, then workflow, then warning. Every sentence is purposeful; no redundant phrasing.
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 8-parameter destructive update with no output schema, the description covers the essential behavioral concerns: full rewrite, clearing of omitted fields, workflow, and the agentKey side effect. It misses explicit error/return behavior, but schema covers parameter detail, so it is sufficiently 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?
Schema coverage is 100%, so the schema fully documents each parameter. The description adds the semantic that the object is a complete replacement, meaning omitted optional fields reset — a meaningful addition to understanding parameter behavior. However, it doesn't add per-parameter syntax or format 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 explicitly states 'Replace a unit by id with its COMPLETE new definition' — a specific verb, resource, and scope. It also distinguishes itself from a partial patch, clearly marking it as a full-update operation distinct from sibling create/archive 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?
It instructs to 'Read the current unit with clocknext_get_unit first, edit, then send the whole object back,' providing a concrete when-to-use workflow. It warns about the agentKey re-pointing effect, but does not explicitly name alternative tools for partial updates, so a 4 rather than 5.
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?
Annotations mark this as a mutating, open-world, idempotent operation; the description adds meaning by explaining the catalog price-copy behavior, the $0-metering edge case with a returned warning/link, and that non-catalog models/providers cannot be added. No contradiction with annotations.
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-loaded with purpose and no filler. Each sentence covers distinct behavior: enabling/metering, catalog pricing, $0 edge case, and catalog prerequisite.
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?
With a 2-param schema, no output schema, and strong annotations, the description covers the full workflow: prerequisites, pricing behavior, return values (link + warning), and failure conditions. It is fully sufficient for an agent to invoke 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?
Both parameters are already fully documented in the schema (100% coverage) with concrete examples and the modelId relationship. The description restates the catalog-id semantics but adds no new parameter-level detail beyond what the schema provides, so a 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 opens with a specific verb+resource: 'Enable a model for the organisation so usage can be metered against it.' It clearly distinguishes the tool from siblings by noting the resulting modelId becomes valid in clocknext_record_usage/clocknext_verify_signal and appears in clocknext_list_models.
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?
It gives when-to-use context (enable for metering), a prerequisite ('check clocknext_list_models first'), and clear exclusions: only catalog models can be added, and you 'never set prices here', directing price-setting to the Models page. This explicitly routes to the right tool and away from alternatives.
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?
Despite annotations (destructiveHint=true, idempotentHint=true), the description adds crucial context: soft archive, data retention, continued operation of existing plans, reversibility, and absence of a separate un-archive tool. It clarifies the non-destructive nature, which goes beyond the raw annotation.
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 compact yet information-dense. Four sentences deliver purpose, effects, reversibility, and usage constraints without unnecessary words. Every sentence earns its place.
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 single-parameter, no-output-schema tool, this description fully covers the behavior, side effects, reversibility, and scope. It explains consequences to existing plans and active lists, making it 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 schema already describes the 'id' parameter as 'The unit id to deactivate (soft-archive — reversible, not a delete).' The tool description adds no new 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?
The description states a specific verb and resource: 'Deactivate a unit TYPE in your catalogue (sets isActive→false)'. It clearly distinguishes from sibling archive tools by specifying 'unit' and even clarifies unrelated actions like 'archiving a customer'.
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?
Explicit guidance is provided: 'Use ONLY to retire a unit you no longer sell.' It also contrasts with deletion, and points to an alternative for reactivation via clocknext_update_unit. This fully addresses when and when not to use the 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?
The description explicitly discloses that this is a full rewrite, not a partial patch, and that omitted steps/fields are dropped. It also reveals that step prices are re-grounded from the models mixer and warns that agent keys are runtime bindings that must be changed deliberately, providing substantial context beyond the annotations.
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 essential semantics of full replacement and the prerequisite of reading first. Every sentence contributes operational value with no filler or redundancy.
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 complexity of nested steps and model mixers, the description covers the main pitfalls: full rewrite semantics, read-before-update, and agent key sensitivity. Combined with the exhaustive schema, the agent has sufficient information to invoke the tool 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?
The schema covers all parameters at 100%, but the description adds critical semantic context about the 'complete new definition' rewrite behavior and re-grounding of step prices. This clarifies how the parameters interact, exceeding the baseline for a fully covered 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 opens with 'Replace an outcome by id' which clearly identifies the verb and resource, and the phrase 'COMPLETE new definition' distinguishes it from create/archive/get. This specificity 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear prerequisite by instructing to read the current outcome with clocknext_get_outcome first, and references 'same as create' to set expectations. While it doesn't explicitly contrast with alternatives, the guidance effectively indicates when 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description discloses critical behaviors: complete replacement, omitted fields dropped, changes apply only going forward, and existing customers keep their terms. This is valuable context that annotations (readOnlyHint, openWorldHint, idempotentHint) do not convey.
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 earning its place: the first defines the operation, the second notes side effects, the third gives a clear workflow. No fluff or duplication of schema content.
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 rich input schema, annotations, and no output schema, the description adequately covers the essential context: full rewrite semantics, forward-looking effect, and prerequisite workflow. It is complete enough for an agent to invoke 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 description coverage is 100% and property descriptions are detailed, so baseline is 3. The description adds parameter-level meaning by emphasizing that the payload must be a complete definition (same shape as create) and that omitted fields are dropped, which affects how callers should construct the object.
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 ('Replace'), names the resource ('a plan by id'), and clarifies the semantics ('a full rewrite, not a patch; omitted fields are dropped'). This clearly distinguishes it from sibling tools like clocknext_create_plan and clocknext_archive_plan.
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 operational guidance: 'Read it first with clocknext_get_plan, edit, then send the whole thing back.' It implies a full overwrite use case and discourages partial edits, though it does not enumerate alternatives or state 'when not to use' explicitly.
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?
The description goes well beyond the annotations (readOnly=false, destructive=true, idempotent=true) by explaining what exactly is kept (outcome, steps, history), what is affected (new plans only), reversibility, and that it's not a delete. It adds context about the soft-archive semantics without contradicting the annotations.
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?
Despite being multi-sentence, every sentence contributes essential information: the operation, what's preserved, what's affected, reversibility, and exclusions. It is front-loaded with the main action and avoids redundancy.
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 (soft archive, reversible, with side effects), the description covers all necessary context: what happens, what doesn't happen, how to reverse, and when to use. With no output schema, it doesn't need to explain return values, and the annotations already handle idempotency and destructiveness.
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 already covers the single parameter (id) with a description. The description adds value by clarifying that the id refers to an outcome TYPE and explains the effect (sets isActive→false), which supplements the schema description.
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 defines the operation with a specific verb and resource: 'Deactivate an outcome TYPE' and clarifies it's a soft archive, not a delete. It clearly distinguishes from sibling tools like clocknext_archive_plan and clocknext_archive_credit by stating it's not related to archiving customers or ending purchases.
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?
Provides explicit when-to-use guidance ('Use ONLY to retire an outcome you no longer sell'), when-not-to-use context ('unrelated to archiving a customer or ending a purchase'), and an explicit alternative for reversing (reactivate via clocknext_update_outcome with isActive:true).
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

Copy to your README.md:

[![clocknext-mcp MCP server](https://glama.ai/mcp/servers/ClockNext/clocknext-mcp/badges/card.svg)](https://glama.ai/mcp/servers/ClockNext/clocknext-mcp)

Score Badge

Copy to your README.md:

[![clocknext-mcp MCP server](https://glama.ai/mcp/servers/ClockNext/clocknext-mcp/badges/score.svg)](https://glama.ai/mcp/servers/ClockNext/clocknext-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ClockNext/clocknext-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server