The TimeIQ MCP Server enables AI agents (e.g., Claude Desktop, Cursor, Hermes) to manage and automate the full spectrum of TimeIQ time tracking operations. Here's what you can do:
Time Tracking & Timers – Create, update, and delete time entries (by start/end time or duration); bulk update/delete entries; start, stop, cancel, and update running stopwatch timers.
Projects & Clients – List, create, update, delete, archive, and re-activate projects and clients; bulk update multiple projects at once.
People & Capacity – View your own profile/permissions (whoami); manage team members (list, create, update, archive, delete — Admin only); get/set required working capacity; update personal preferences.
Reports & Analytics – Generate standard, classic, custom, payroll, and period summary reports; produce detailed time/expense reports; identify missing or incomplete time entries; search across all time and expense entries; view recent activity feeds.
Expenses – Create, update, and delete expense entries (bulk supported); manage expense types and categories (create, update, archive, delete).
Services – Manage billable services and service categories (list, create, update, archive, delete).
Timesheets & Approvals – List, retrieve, and submit timesheets; approve or decline timesheets (Manager/Admin); find timesheets with issues; send approval reminders.
Invoices – List, create, update, and delete invoices; mark as paid/unpaid/written-off; manage line items; send invoices.
Notifications – Fetch and dismiss active notifications; trigger missing-time and timesheet-approval email reminders.
System Settings – Retrieve and update tenant-wide preferences and timezone settings.
Safety Features – A dry_run mode simulates mutating operations before execution; a bulk action gate requires confirmation for operations on 50+ records.
Exposed Resources – Read-only access to JSON schemas for primary entities, the TimeIQ endpoint specification, and a snapshot of the acting user's profile and permissions.
Provides Slack member ID mapping, allowing secure linking of Slack user IDs to TimeIQ user accounts for enforcing user boundaries.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@TimeIQ MCP Server show my time entries for today"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Version 1.3 Created by Timothy Maximilian Scherman (www.timothyscherman.de / www.schild-roth.com) with the purpose of making agency life in the service and service-business area a bit easier, and equipping own AI agents with the ability to create time entries as well as automatically adding regularly recurring items via cron jobs.
A production-ready, fully anonymized Model Context Protocol (MCP) server for TimeIQ time tracking. It provides a standard integration pattern that allows LLM agents (like Claude Desktop, Cursor, or custom gateway agents running on Hermes) to view and manage time entries, projects, clients, reports, invoices, expenses, services, and timesheets via a secure stdio transport.
Anonymized & Secure by Design: Zero hardcoded credentials or branding (no mentions of internal subdomains, private domains, or local credentials).
Interactive Setup Wizard: Run npx timeiq-mcp setup to automatically generate all env maps, define Slack admins/coworkers interactively, and get copy-paste ready config snippets.
Safe-by-Default (Dry-Run): Defaults to TIMEIQ_DRY_RUN=true to prevent agents from inadvertently creating, modifying, or deleting entries. All modification requests describe the intended action without executing it.
Bulk Action Gate: Forces safety confirmation for multi-record operations.
Complete Reverse-Engineered Coverage: Exposes 50+ tools and 3 read-only resources spanning the entire TimeIQ SPA API.
In-Memory Session Security: Employs an in-memory session cookie jar (zero tokens or cookies are persisted to disk).
Robust Timezone & Input Handling: Strict date validation (prevents JS calendar rollover bugs like 2026-02-30 silently resolving to March 2nd) and automatic snake_case slugifiers that convert names with German diacritics and umlauts (e.g., ä → ae, ß → ss).
Slack Member ID Mapping & Security: Supports the TIMEIQ_SLACK_MAP environment variable to securely map Slack user IDs directly to individual coworker emails, ensuring hard user-level data ownership and action boundaries.
Related MCP server: Calq MCP
This MCP setup was primarily designed for integration with the Hermes agent (Zweibot). It runs flawlessly on your remote VPS container and enables frictionless, real-time time tracking and project management directly via Slack.
Universal MCP Compatibility: Because this server fully conforms to the Model Context Protocol (MCP) specification, any other AI assistant or client (such as Claude Desktop, Cursor, Cline, Windsurf, or Cloud Coworker) can integrate and work with it immediately out of the box with zero custom adjustments.
Here are concrete, real-world examples of natural language prompts you can give to your AI coworker (e.g. Hermes in Slack or Claude in Claude Desktop/Cursor), along with the corresponding MCP tools mapped under the hood:
Query: “Please book 15 minutes today on the project '[Client Name] - SEO monatlich' with the description: Developing content strategy.”
MCP Tool: timeiq_time_create (using start_time and end_time or duration style).
Query: “I worked on the website today from 10:00 AM to 11:30 AM. Please log that time.”
MCP Tool: timeiq_time_create (automatically parses and converts the duration to 90 minutes).
Query: “Delete my time entry with the ID 44088.”
MCP Tool: timeiq_time_delete.
Query: “Start a stopwatch for the 'Marketing Campaign' project and set the topic to 'Create social media post'.”
MCP Tool: timeiq_timer_start.
Query: “How long has my current stopwatch been running and what am I working on?”
MCP Tool: timeiq_timer_get.
Query: “Change the notes of my active timer to 'Review round with the client'.”
MCP Tool: timeiq_timer_update (routes a flat PUT payload to the correct /actions/updateTimeEntry API endpoint).
Query: “I'm finished, please stop the stopwatch and save the time.”
MCP Tool: timeiq_timer_stop (stops the running timer and persists the time entry).
Query: “Cancel the active stopwatch and discard the time.”
MCP Tool: timeiq_timer_cancel (deletes the running stopwatch without creating any time entry).
Query: “Show me a list of all our active projects.”
MCP Tool: timeiq_project_list (filtered by active).
Query: “Can you please archive the 'Insurance Directory' project?”
MCP Tool: timeiq_project_archive (safely looks up the project ID and archives it via bulk-routing).
Query: “Create a new client named 'ACME GmbH' and set up a project called 'Web Design 2026' for them.”
MCP Tools: timeiq_client_create followed by timeiq_project_create.
Query: “Generate a report for this week and show me the total hours booked.”
MCP Tool: timeiq_report_standard (returns high-level summary KPIs).
Query: “Search for all my time entries logged today.”
MCP Tool: timeiq_report_search_time (executes search utilizing double-nested parameters).
Query: “Are there any coworkers who have not completed their required hours this week?”
MCP Tool: timeiq_report_missing_time.
Query: “Show me all invoices for '[Client Name]' from this year.”
MCP Tool: timeiq_invoice_list_for_client.
Query: “Log a new expense of 45 € for 'Train Ticket' on the project 'SEO monatlich'.”
MCP Tool: timeiq_expense_create.
Query: “Mark invoice number RE-2026-004 as fully paid.”
MCP Tool: timeiq_invoice_mark_paid (resolved dynamically using timeiq_invoice_get_by_number).
Query: “Submit my timesheet for the current period for approval.”
MCP Tool: timeiq_timesheet_submit (automatically fetches the active period and submits it).
Query: “Who am I in TimeIQ and what are my permissions?”
MCP Tool: timeiq_whoami (retrieves full profile details from /api/people/me).
Node.js >= 20.0.0
To configure the server, map Slack User IDs to emails, and generate config blocks instantly, run the zero-dependency interactive setup CLI wizard:
npm run setupor directly via:
npx timeiq-mcp setupThe wizard will guide you through:
Entering your TimeIQ Tenant subdomain, email, and password.
Specifying the Admin Slack User ID (which maps to your admin email).
Sequentially adding as many coworker Slack User IDs and corresponding TimeIQ Emails as you want.
Setting the default safety mode (Dry-run).
Once completed, it will automatically:
Create/update a local .env file in the working directory.
Render copy-paste-ready config blocks for both Claude Desktop and Hermes (config.yaml).
Display a clear role/user mapping table for verification.
Configure the following environment variables. The server will validate them on startup using Zod:
Variable | Type | Default | Description |
|
| Required | Your TimeIQ tenant subdomain (e.g., |
|
| Required | The acting user's email address (or Admin service account). |
|
| Required | The acting user's password. |
|
|
| Optional. A JSON mapping of Slack user IDs to TimeIQ emails (e.g. |
|
|
| Safety Mode. If |
Add this to your claude_desktop_config.json:
{
"mcpServers": {
"timeiq-mcp": {
"command": "npx",
"args": ["-y", "timeiq-mcp"],
"env": {
"TIMEIQ_TENANT": "your-tenant",
"TIMEIQ_EMAIL": "your-email@example.com",
"TIMEIQ_PASSWORD": "your-password",
"TIMEIQ_DRY_RUN": "true"
}
}
}
}Go to Settings > Features > MCP.
Click + Add New MCP Server.
Fill in the details:
Name: timeiq-mcp
Type: command
Command:
env TIMEIQ_TENANT="your-tenant" TIMEIQ_EMAIL="your-email@example.com" TIMEIQ_PASSWORD="your-password" TIMEIQ_DRY_RUN="true" npx -y timeiq-mcpTo integrate the server with remote gateway bots, register the tool inside the bots' local config.yaml and boot:
mcp:
servers:
timeiq-mcp:
command: "npx"
args: ["-y", "timeiq-mcp"]
env:
TIMEIQ_TENANT: "your-tenant"
TIMEIQ_EMAIL: "admin-account@example.com"
TIMEIQ_PASSWORD: "secure-password"
TIMEIQ_DRY_RUN: "false" # Set to false to allow actual actions
TIMEIQ_SLACK_MAP: '{"U12345678": "cara@example.com", "U87654321": "emily@example.com"}'The server exposes modular tools mapped across 10 distinct domains:
time.ts)timeiq_time_list_me: List acting user's time entries in a date range. Defaults to today.
timeiq_time_list_person: Admin only. Retrieve time entries for another user.
timeiq_time_create: Create a time entry (supports both start/end time and duration style).
timeiq_time_create_overbook: Create a time entry with budget warnings.
timeiq_time_update: Update a single time entry using automatic changeset comparison.
timeiq_time_delete: Delete a single time entry.
timeiq_time_delete_many: Delete multiple time entries by ID list.
timeiq_time_update_many: Apply bulk updates to a list of time entries.
timeiq_time_batch: Week-grid-style batch updates.
timeiq_timer_get: Get currently running stopwatch.
timeiq_timer_start: Start a new running timer.
timeiq_timer_stop: Stop running timer and convert to a time entry.
timeiq_timer_cancel: Cancel active timer.
timeiq_timer_update: Update active timer notes/project.
timeiq_timer_update_entry: Update underlying entry of active timer.
projects.ts)timeiq_project_list: List projects. Can filter by active, archived, managed, or managed_archived.
timeiq_project_get: Get single project details by slug.
timeiq_project_create: Create a project (auto-slugifies names).
timeiq_project_update: Update project attributes.
timeiq_project_update_many: Update multiple projects in one call.
timeiq_project_delete: Delete a project.
timeiq_project_archive: Archive a project.
timeiq_project_activate: Re-activate an archived project.
timeiq_client_list: List clients. Can filter by active, archived, managed, or managed_archived.
timeiq_client_get: Get client details by slug.
timeiq_client_create: Create client.
timeiq_client_update: Update client.
timeiq_client_delete: Delete client.
timeiq_client_archive: Archive a client.
timeiq_client_activate: Re-activate an archived client.
people.ts)timeiq_whoami: Get profile and settings of currently authenticated acting user.
timeiq_person_list: List team members. Can filter by active, archived, managed, or managed_archived.
timeiq_person_get: Get single team member by slug.
timeiq_person_create: Create new person (Admin only).
timeiq_person_update: Update person details (Admin only).
timeiq_person_delete: Delete a person (Admin only).
timeiq_person_archive: Archive a coworker.
timeiq_person_activate: Re-activate a coworker.
timeiq_person_update_preferences: Update own preferences.
timeiq_person_required_time_get: Get capacity settings for a person.
timeiq_person_required_time_set: Set capacity values for a person.
reports.ts)timeiq_report_standard: Overview report (summary card data).
timeiq_report_standard_time: Standard report time-tab entries.
timeiq_report_standard_expenses: Standard report expenses.
timeiq_report_time: Time summary totals & group-by breakdowns.
timeiq_report_time_detail: Detailed time-entry report list.
timeiq_report_expenses: Summary expense report.
timeiq_report_expenses_detail: Detailed expense report list.
timeiq_report_classic: Classic summary report.
timeiq_report_classic_time: Classic time report.
timeiq_report_custom: Custom report with custom parameters.
timeiq_report_period: Period-aligned timesheet report.
timeiq_report_payroll: Payroll summaries for staff.
timeiq_report_recent_activity: Feed of latest changes.
timeiq_report_missing_time: Identify people missing capacity entries.
timeiq_report_incomplete_time: Identify people with incomplete times.
timeiq_report_search_time: Search across time entries.
timeiq_report_search_expenses: Search across expense entries.
expenses.ts)timeiq_expense_list_me: List expense entries for the acting user.
timeiq_expense_list_person: List expense entries for another user.
timeiq_expense_create: Log new expense (travel, software, etc.).
timeiq_expense_update: Update logged expense.
timeiq_expense_delete: Delete expense.
timeiq_expense_delete_many: Delete multiple expenses.
timeiq_expense_update_many: Apply updates to multiple expenses.
timeiq_expense_type_list: List expense types.
timeiq_expense_type_get: Get single expense type by slug.
timeiq_expense_type_create: Create expense type.
timeiq_expense_type_update: Update expense type.
timeiq_expense_type_delete: Delete expense type.
timeiq_expense_type_archive: Archive an expense type.
timeiq_expense_type_activate: Re-activate an expense type.
timeiq_expense_category_list: List expense categories.
timeiq_expense_category_create: Create expense category.
timeiq_expense_category_update: Update expense category.
timeiq_expense_category_delete: Delete expense category.
timeiq_expense_category_archive: Archive an expense category.
timeiq_expense_category_activate: Re-activate an expense category.
services.ts)timeiq_service_list: List billable services (tasks).
timeiq_service_create: Create billable service.
timeiq_service_update: Update service.
timeiq_service_delete: Delete service.
timeiq_service_archive: Archive a service.
timeiq_service_activate: Re-activate a service.
timeiq_service_category_list: List service categories.
timeiq_service_category_create: Create service category.
timeiq_service_category_update: Update service category.
timeiq_service_category_delete: Delete service category.
timeiq_service_category_archive: Archive a service category.
timeiq_service_category_activate: Re-activate a service category.
timesheets.ts)timeiq_timesheet_period_list: List all timesheet periods.
timeiq_timesheet_period_by_date: Get the timesheet period covering a specific date.
timeiq_timesheet_period_get: Get details for a single timesheet period by ID.
timeiq_timesheet_list: List timesheets for the acting user.
timeiq_timesheet_get: Get details for a single timesheet by ID.
timeiq_timesheet_by_date: Get the timesheet covering a specific date.
timeiq_timesheet_with_issues: List timesheets flagged with issues.
timeiq_timesheet_neighbors: Fetch neighbor timesheets.
timeiq_timesheet_submit: Submit a timesheet for review and approval.
timeiq_timesheet_approve: Approve a submitted timesheet (Manager/Admin only).
timeiq_timesheet_decline: Decline/reject a submitted timesheet (Manager/Admin only).
timeiq_timesheet_send_reminder: Trigger a missing timesheet submission email reminder.
invoices.ts)timeiq_invoice_list: List all invoices, optionally filtered by date range.
timeiq_invoice_list_for_client: List all invoices for a specific client.
timeiq_invoice_get: Get details of a single invoice by its ID.
timeiq_invoice_get_by_number: Get a single invoice by its alphanumeric invoice number.
timeiq_invoice_create: Create a new draft invoice.
timeiq_invoice_update: Update an invoice (e.g. details, dates, comments).
timeiq_invoice_delete: Delete an existing invoice by ID.
timeiq_invoice_mark_paid: Mark an invoice status as fully paid.
timeiq_invoice_mark_unpaid: Mark a paid or drafted invoice status as unpaid.
timeiq_invoice_mark_written_off: Mark an invoice status as written-off.
timeiq_invoice_send: Trigger the invoice-send email.
timeiq_invoice_export: Get invoice export/PDF compile details.
timeiq_lineitem_add: Add a new line item details row to an existing invoice.
timeiq_lineitem_update: Update a single line item details row on an invoice.
timeiq_lineitem_delete: Remove a line item details row from an invoice.
notifications.ts)timeiq_notifications_list: Fetch active notifications.
timeiq_notifications_dismiss: Dismiss notification by ID.
timeiq_notifications_remind_missing: Trigger missing-time email reminder to a user.
timeiq_notifications_remind_timesheet: Trigger timesheet-approval reminder.
settings.ts)timeiq_settings_get: Get tenant-wide preferences.
timeiq_settings_update: Update system configuration parameters.
timeiq_settings_timezones: Retrieve active timezone choices.
The server exposes three read-only resources through standard URI schemes:
timeiq://schemas: Dynamically dumps complete JSON schemas of all primary entities (Person, Client, Project, TimeEntry, Invoice, etc.) derived from strict Zod schemas.
timeiq://endpoints: The entire reverse-engineered specification of the TimeIQ HTTP endpoints, allowing the LLM to inspect route constraints and exact payloads.
timeiq://me: A snapshot of the currently acting user's profile and permission configuration (cached for 60 seconds).
When running in Dry-Run mode (TIMEIQ_DRY_RUN=true), any mutating operation returns a simulated response structured identically to the actual API response:
{
"dry_run": true,
"request": {
"method": "POST",
"path": "/api/time",
"body": {
"date": "2026-05-29",
"project_id": 2070,
"duration": 60,
"notes": "Testing the MCP Server safely"
}
}
}npm installThe test suite utilizes Vitest to validate strict dates, slugifiers, and partial changeset generation:
npm run testnpm run buildThis project is licensed under the MIT License.
Get the current TimeIQ subscription plan and billing credit card details.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It states 'Get', indicating a read operation, but lacks details on permissions, rate limits, error handling, or response behavior. Basic but insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 12 words, front-loaded with the verb 'Get'. It is concise and contains no unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (0 parameters, no output schema), the description is adequate. However, it does not describe the return format or potential errors, which would improve completeness for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema description coverage is 100% (trivially). The description adds no parameter details, but this is acceptable as no parameters exist. Baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs and resources: 'Get the current TimeIQ subscription plan and billing credit card details.' It clearly distinguishes from sibling tools like timeiq_billing_invoices by focusing on subscription plan and credit card details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving billing information but does not provide explicit guidance on when to use this tool versus alternatives like timeiq_billing_invoices or timeiq_settings_get. No when-not-to-use or alternative recommendations are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all past TimeIQ subscription SaaS billing invoices.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states a list operation without mentioning pagination, ordering, or any other behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that efficiently communicates the tool's purpose without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, annotations, or output schema, the description lacks details about the output format, limits, or additional behavior. It is minimal for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters and coverage is 100%, so baseline is 3. The description adds no parameter information, but none is needed given the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists past subscription SaaS billing invoices, specifying the verb 'List' and the resource 'past TimeIQ subscription SaaS billing invoices'. This distinguishes it from siblings like timeiq_invoice_list which may cover all invoices.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as timeiq_invoice_list or timeiq_billing_info. It lacks context about appropriate use cases or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-activate an archived client (sets isActive to true).
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the core mutation (sets isActive to true) but omits details on permissions, side effects, or error conditions (e.g., if client is already active). This is minimally adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 11 words, front-loading the key action and effect. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one param, no output schema), the description provides the essential purpose and effect but lacks details on permissions, error states, and response. It is minimally complete for a basic mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for the single parameter 'slug'. The description does not explain what 'slug' represents, leaving the agent to infer its meaning. This is a significant gap since parameter semantics are not compensated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (re-activate), the resource (archived client), and the internal effect (sets isActive to true). It distinguishes itself from sibling tools like timeiq_client_archive and timeiq_client_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives, nor does it provide prerequisites or context. The name and implication suggest it is the inverse of archive, but explicit guidance is lacking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Archive an active client (sets isActive to false).
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states the core mutation (sets isActive to false) but omits any side effects, reversibility, or access implications for related data (invoices, projects).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action and effect. No unnecessary words, though additional details could be added without harming conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (1 param, no output schema, no annotations) and the large set of sibling tools, the description lacks usage guidance and behavioral context, leaving gaps for safe and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage for the single parameter 'slug' is 0%. The description does not explain what 'slug' represents (e.g., client identifier format) beyond the tool's context, adding minimal value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Archive', the resource 'client', and the effect 'sets isActive to false'. It distinguishes from sibling tools like timeiq_client_delete or timeiq_client_activate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, no prerequisites mentioned, and no when-not-to-use context. The description implies the client must be active but does not explicitly state it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new client.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| isActive | No | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should inform about side effects or safety. It only says 'create', with no mention of required permissions, default values, or result behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise but at the cost of essential information. It could be expanded without losing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's three parameters, lack of output schema, and no annotations, the description is insufficient for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description adds no meaning to the three parameters. The agent cannot infer the role of 'isActive' or 'dry_run'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new client. It is specific enough to distinguish from sibling tools that activate, archive, or delete clients.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an existing client by its slug.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It only states 'Delete', implying destructiveness, but lacks details on side effects, permissions, or reversibility. No contradictions since no annotations exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that immediately conveys the core function. However, it may be too terse given the need for behavioral context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no output schema and no annotations, the description is insufficient. It does not address return values, error behavior, or the effect of dry_run, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description explains the slug parameter's role but omits the dry_run parameter entirely, failing to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Delete' and the resource 'client' with the identifier 'slug', distinguishing it from sibling tools like timeiq_client_archive or timeiq_client_deactivate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, no prerequisites or exclusions mentioned. The description simply states the action without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single client by their slug.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only says 'Get', implying a read operation, but fails to mention potential errors (e.g., if slug not found), authentication needs, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at one sentence, front-loading the essential information with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-slug tool with one required parameter and no output schema, the description is functional but lacks details on return values and error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds minimal meaning beyond the schema by stating 'by their slug,' but schema coverage is 0%. No examples, format, or constraints are provided for the slug parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a single client by their slug,' which is a specific verb (get) and resource (client) with the unique identifier (slug). It effectively distinguishes from sibling tools like timeiq_client_list, timeiq_client_create, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It does not mention when not to use it or what to use instead, such as timeiq_client_list for multiple clients.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List clients. Can filter by active, archived, managed, or managed_archived.
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | active |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as pagination, sorting, limits, or whether the list returns all clients. This leaves the agent uninformed about the tool's behavior beyond basic listing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single sentence that efficiently conveys both purpose and available parameters. No unnecessary words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter, the description covers the essential purpose and parameter. However, it lacks information about return structure, pagination, or constraints, making it minimally complete but with gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explicitly lists the filter options and their intended use ('active, archived, managed, or managed_archived'), adding meaning beyond the schema's enum list. However, it does not explain the semantics of each filter (e.g., what 'managed' means) in detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List clients' as the verb and resource, and specifies the filtering options (active, archived, managed, managed_archived). This differentiates it from sibling tools like timeiq_client_get (single client) and timeiq_client_activate/archive (mutations).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates that this tool is for listing clients with filters, but it lacks explicit guidance on when to use this over alternatives like timeiq_client_get for retrieving a single client. No when-not-to-use or context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing client by their slug with a partial changeset.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| changeset | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It indicates mutation ('Update'), but does not disclose idempotency, error handling, side effects, or return behavior. For a write operation, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. Every part is relevant and efficiently conveys the core operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 3 parameters, no output schema, and no annotations, the description leaves many gaps. It does not specify success/error responses, required permissions, or whether the update is partial. More detail is needed for an agent to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It mentions 'slug' and 'partial changeset', but does not explain slug format, changeset structure, or dry_run purpose. The description adds minimal value beyond parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Update), resource (client), identifier (by slug), and nature (partial changeset). It is distinct from sibling tools like create, delete, get, list, activate, archive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when or when-not guidance. The description implies usage for updating an existing client, but does not mention alternatives or prerequisites. Compared to siblings, the purpose is clear but without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Activate a previously archived expense category (sets isActive to true).
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It states the mutation action and effect, but does not disclose reversibility, error states (e.g., slug not found), or required permissions. Basic transparency, but could be more explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, 13 words, directly states action and effect. No wasted words or unnecessary details. Excellent conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple toggle tool, the description is mostly adequate, but it lacks explanation of the parameter and potential error cases. Could be more complete for an agent to use without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameter 'slug' has no description in the schema (0% coverage) and the description does not explain what a slug is or how to obtain it. It only indirectly implies it should be a slug of an archived category. Insufficient compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (activate), the resource (expense category), and the effect (sets isActive to true). It distinguishes from sibling tools like 'archive' by specifying it is for previously archived categories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (for previously archived categories) but lacks explicit guidance on prerequisites (e.g., slug must exist, category must be archived) and alternatives. No mention of 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.
Archive an expense category (sets isActive to false).
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. It mentions setting isActive to false but omits details like reversibility, permission requirements, or impact on associated expenses. Lacks depth for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no redundant words, front-loaded with verb and resource. Efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite low complexity, description lacks critical context: no explanation of return value, no prerequisites, no mention of irreversible consequences. Does not fully equip the agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the single parameter 'slug'. Description does not clarify what slug represents or how to obtain it, leaving the agent with no guidance beyond parameter name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Archive an expense category' with the specific behavior 'sets isActive to false'. This differentiates it from sibling tools like activate, delete, or update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Context signals show siblings like timeiq_expense_category_activate and timeiq_expense_category_delete, but description provides no comparison or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new expense category.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| isActive | No | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a write operation ('Create') but does not disclose any behavioral traits such as authentication requirements, side effects, error conditions, or idempotency. With no annotations, the description carries the full burden and fails to provide adequate transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (6 words) but is under-specified. It is not concise in a positive sense because it adds no value beyond the tool name, wasting the opportunity to inform the agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations, output schema, and parameter descriptions, the description is entirely incomplete. The agent receives no guidance on return values, error handling, or operational context, making the tool difficult to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description makes no mention of any parameters. The input schema has 3 parameters (name, isActive, dry_run) with 0% schema coverage, so the agent is left to infer meaning solely from parameter names and types, which is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new expense category.' is a tautology that merely restates the tool name. It adds no additional context or differentiation from sibling tools, which are distinguished by verb but the description does not provide any unique details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not indicate when to use this tool versus alternatives, nor does it list prerequisites, typical use cases, or scenarios where the tool would be inappropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an existing expense category by its slug.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description labels the action as delete but lacks details on consequences (e.g., is it permanent?, what happens to associated data?). No annotations are provided to fill the gap, and the dry_run parameter is absent from the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no waste, but it is too brief for the complexity of the tool and fails to include necessary details about parameters or usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, no annotations, and two parameters (one undocumented), the description does not sufficiently inform the agent about prerequisites, side effects, or how to safely execute the deletion.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions 'by its slug' but does not explain what slug is or how to obtain it. The dry_run parameter is not described, leaving its purpose unclear despite 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete), resource (expense category), and identifier (slug), distinguishing it from sibling tools like create, update, or list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like archive or activate. The dry_run parameter is not explained in the description, missing an opportunity to clarify testing usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List active expense categories. Optional toggle to list archived instead.
| Name | Required | Description | Default |
|---|---|---|---|
| archived | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It discloses default behavior (listing active) and the toggle for archived, but lacks details on pagination, sorting, or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise, front-loaded, and efficient. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers the main functionality. The absence of output schema is acceptable for a list tool, but some details on what the list contains could improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description explains the sole parameter 'archived' meaningfully, compensating for the schema gap by clarifying its effect.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists active expense categories and provides an optional toggle for archived categories, distinguishing it from other expense category tools like create or update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives such as timeiq_expense_category_get or other list tools. Usage is implied but not clarified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing expense category by its slug with a partial changeset.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| changeset | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'partial changeset' implying PATCH semantics, but fails to describe side effects (e.g., does it modify other fields?), error handling (e.g., if slug does not exist), or authentication requirements. This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant words. It is front-loaded with the verb and resource, making it easy to scan. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 parameters, nested object, no output schema) and no annotations, the description should explain return value, error behavior, and effect on other fields. It lacks these details, leaving the agent with significant unknowns for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% schema description coverage, so the description must compensate. It explains 'slug' and 'partial changeset' but does not detail what fields the changeset can contain (e.g., name, color) or what 'dry_run' does. The description adds minimal meaning beyond stating the presence of these parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update', the resource 'expense category', the identifier 'by its slug', and the method 'with a partial changeset', leaving no ambiguity about what the tool does. It distinguishes from sibling tools like timeiq_expense_category_create or timeiq_expense_category_activate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for updating an existing expense category, but provides no explicit guidance on when to use this tool versus alternatives like timeiq_expense_category_create for new categories or timeiq_expense_category_archive for deactivation. No when-not-to-use or prerequisite information is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new expense entry.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | ||
| project_id | Yes | ||
| amount | Yes | ||
| notes | No | ||
| expense_type_id | No | ||
| is_billable | No | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits such as whether the operation is destructive (likely yes), authentication requirements, error handling, or side effects. The single sentence fails to convey essential behavior beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of one short sentence. While brevity is good, it sacrifices essential information, making it insufficient for an agent to understand the tool's purpose. The structure lacks any elaboration or context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, no output schema, no annotations), the description is grossly inadequate. It does not explain return values, side effects, or parameter dependencies, leaving the agent with insufficient information to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for its 7 parameters, yet the description adds no information about parameter meanings, formats, or constraints. For example, what 'date' format is expected? How is 'is_billable' used? The description is entirely silent on parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new expense entry,' specifying the verb and resource. It differentiates from sibling tools like timeiq_expense_update or timeiq_expense_delete through the use of 'create' in both name and description. However, it could be more specific about the scope or required fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as timeiq_expense_update or timeiq_expense_create_many. There is no mention of prerequisites, contexts, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an existing expense entry by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and description only states basic delete operation. Does not disclose side effects, permissions, reversibility, or behavior on non-existent ID.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, concise but lacks structure. Could include information about dry_run parameter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Minimal description for a tool with no annotations, no output schema, and an undocumented boolean parameter. Does not provide enough context for safe use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description mentions id parameter implicitly but does not explain dry_run parameter. Schema has 0% coverage, so description adds almost no value beyond parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (delete), resource (expense entry), and identifier (by ID). Distinguishes from sibling like timeiq_expense_delete_many by specifying single entry.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like timeiq_expense_delete_many. Does not mention prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete multiple expense entries. Safe-guarded for actions exceeding 50 entries.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | ||
| confirm_bulk | No | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Mentions a safeguard for exceeding 50 entries but does not explain the safeguard mechanism (e.g., how confirm_bulk parameter interacts) or other behavioral traits like reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences are concise and front-loaded, but the brevity sacrifices necessary detail given the lack of annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Does not cover parameter usage, the safeguard behavior, or return values, leaving significant gaps for a tool with no annotations or output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain any parameters (ids, confirm_bulk, dry_run). The mention of '50 entries' is related to id count but not tied to parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action ('Delete multiple expense entries') and resource, clearly distinguishing it from the single-delete sibling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for multiple entries (vs. single delete) but lacks explicit when-to-use or when-not-to-use guidance, and does not mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List expense entries for the acting user within a date range.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | No | ||
| end_date | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description alone must convey behavioral traits. It only says 'list', implying read-only, but does not mention pagination, ordering, limits, or safety. Lacks detail for a safe operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. Front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple list tool, but lacks details on pagination, ordering, or output structure. Could be more helpful given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage. Description adds that parameters define a date range, but does not specify format, constraints (inclusive/exclusive), or behavior when omitted. Adds context but insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'list', resource 'expense entries', scope 'for the acting user', and condition 'within a date range'. Distinguishes from sibling timeiq_expense_list_person by user scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicitly indicates it's for the current user via name 'me', but no explicit guidance on when to use this vs alternatives like timeiq_expense_list_person or other list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List expense entries for a specific person by their slug (Admin only).
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| start_date | Yes | ||
| end_date | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool is read-only and requires admin privileges. However, it does not mention response format, pagination, or date format. Since no annotations are provided, the description carries the full burden, and this is a moderate disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 12 words, conveying essential information without any fluff. Every word contributes to clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 required parameters (slug, start_date, end_date) but the description only references the slug. It does not explain how the date parameters affect the listing or their format. Given no output schema, the description is insufficient for an agent to correctly invoke the tool with proper date inputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions 'by their slug', clarifying that slug identifies the person, but does not explain the slug parameter itself or the start_date/end_date parameters. With 0% schema description coverage, the description adds minimal meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'expense entries for a specific person', and the scope 'by their slug (Admin only)'. It distinguishes the tool from siblings like timeiq_expense_list_me by specifying 'for a specific person' and 'Admin only'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: 'for a specific person' implies it is not for the current user, and 'Admin only' indicates required permissions. It contrasts with timeiq_expense_list_me. However, it does not explicitly state when not to use or list alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Activate a previously archived expense type (sets isActive to true).
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It discloses the core behavior (sets isActive to true) but omits details like required permissions, idempotency, or output. This is minimal but acceptable for a simple toggle action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise and to the point. Every word is necessary and adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with only one parameter and no output schema. The description covers the main action but lacks parameter explanation. For this context, it is reasonably complete but could be improved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain parameters. It fails to define 'slug', leaving the agent to infer what identifier to provide. This is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool activates a previously archived expense type by setting isActive to true. It distinguishes from the sibling 'archive' tool, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when reactivating an archived expense type. It lacks explicit when-not or alternatives but is sufficiently clear given the sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Archive an expense type (sets isActive to false).
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
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 states that archiving sets isActive to false, which is a minimal behavioral disclosure. However, it does not discuss side effects, permissions, or reversibility, which would be helpful for an archive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that conveys the essential information without any wasted words. It is appropriately front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (archive with one parameter) and the presence of a sibling activation tool, the description covers the basic purpose well. However, the lack of parameter explanation and no output schema information leaves some ambiguity, making it adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter 'slug' with 0% description coverage, meaning the schema itself provides no meaning. The description adds no information about what 'slug' is or its format, so it fails to compensate for the schema's lack of detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'archive' and the resource 'expense type', and explains the effect (sets isActive to false). This distinguishes it from the sibling tool 'timeiq_expense_type_activate'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or conditions. It simply states the action without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new expense type.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| isActive | No | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only states the action without disclosing any behavioral traits (e.g., side effects, idempotency, success behavior, error conditions). This is completely inadequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one short sentence), but it sacrifices necessary detail. While not verbose, it lacks structure and fails to earn its place by providing minimal value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description is severely incomplete. It does not explain what an expense type is, what happens upon creation, or how the dry_run parameter affects behavior. The tool is left entirely underspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no meaning to the three parameters (name, isActive, dry_run). The description fails to explain any parameter roles or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('a new expense type'), which is a specific verb+resource combination. However, it does not differentiate from sibling tools like update, activate, or delete, which also operate on expense types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., when to create vs. update or activate). There is no mention of prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an existing expense type by its slug.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only indicates deletion without disclosing potential side effects, authorization needs, or error handling (e.g., what happens if slug doesn't exist).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence that directly conveys the tool's purpose without extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too minimal for a delete operation; it lacks details on return values, error conditions, and parameter behavior, especially given the absence of an output schema and annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should explain parameters. It only mentions 'slug' but does not define what a slug is or how to obtain it, and completely ignores the 'dry_run' parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete), resource (expense type), and identifier method (by slug). It distinctly differentiates from siblings like activate, archive, create, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or conditions for deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single expense type by its slug.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
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 states 'Get', indicating a read-only operation, but does not disclose any behavioral traits such as authentication requirements, rate limits, error handling, or what happens if the slug does not exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. It conveys the essential information efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks information about the return value (e.g., expense type object or error) and does not cover edge cases like not found. For a simple get operation, this is a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds the meaning that the 'slug' parameter is the identifier for the expense type, which is beyond the raw schema (just type and name). However, it does not describe what a slug is or any format constraints, leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'expense type', and specifies the identifier 'slug'. This distinguishes it from siblings like 'timeiq_expense_type_list' (list) and 'timeiq_expense_type_create' (create).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a single expense type by slug is needed, but it does not provide explicit guidance on when to use this tool versus alternatives (e.g., list vs. get) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List active expense types. Optional toggle to list archived types instead.
| Name | Required | Description | Default |
|---|---|---|---|
| archived | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the default behavior (active types) and the toggle, but does not discuss authentication, pagination, or side effects. For a simple read-like operation, the disclosure is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the purpose and includes the optional toggle. There is no redundancy or waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one boolean parameter, no output schema), the description is reasonably complete. It explains the core functionality and the parameter effect, though it could mention default behavior more explicitly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the description adds meaning to the 'archived' parameter by explaining that setting it to true lists archived types instead. This provides clarification beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'expense types', with a distinction between active (default) and archived. This differentiates it from sibling tools like timeiq_expense_type_get (single) and timeiq_expense_type_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the optional toggle for archived types, indicating when to use the parameter. Though it does not explicitly exclude alternatives, the context is clear for a simple list operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing expense type by its slug with a partial changeset.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| changeset | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states it's an update operation with a partial changeset, but fails to disclose any side effects, auth requirements, rate limits, or consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence with 11 words, front-loaded with purpose. It is efficient but could include more information without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, no annotations, and a nested changeset parameter, the description is too minimal. It lacks details on return values, error handling, and practical usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description adds only 'partial changeset' as context, but does not explain the structure of the changeset object, which fields are allowed, or the role of dry_run.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'update', the resource 'expense type', and the method 'by its slug with a partial changeset'. It distinguishes from sibling tools like create, delete, list, get, activate, archive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, no prerequisites, and no mention of the dry_run parameter's purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing expense entry with a partial changeset.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| changeset | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only states 'update' without disclosing behavioral traits like whether it merges or replaces, permissions needed, validation, or return value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the core action with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with nested objects and no output schema or annotations, the description lacks details on return value, error handling, and field constraints, making it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must explain parameters. 'Partial changeset' hints but doesn't describe what fields changeset can contain, id's source, or dry_run's effect, leaving agents guessing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update', the resource 'expense entry', and the concept of a 'partial changeset', which distinguishes it from create, delete, and bulk update tools among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when updating a single expense with only changed fields but does not explicitly specify when to use this versus alternatives like timeiq_expense_update_many or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update multiple expense entries. Safe-guarded for actions exceeding 50 entries.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | ||
| changeset | Yes | ||
| confirm_bulk | No | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions a 'safe-guard for actions exceeding 50 entries' but does not explain whether this triggers a confirmation, limits the update, or has other effects. It also omits details on permissions, atomicity, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences, and the first sentence clearly states the action. However, it could be more front-loaded by immediately mentioning the safeguard. No wasteful repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, nested object, no output schema), the description is woefully incomplete. It fails to explain the role of each parameter, the safeguard mechanism, expected behavior, or return values. This leaves an agent without sufficient guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description adds no meaning to any parameter. It does not explain the 'changeset' object (what fields are allowed), the purpose of 'confirm_bulk' and 'dry_run', or how 'ids' are used. This is a critical gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update multiple expense entries', specifying the verb and resource. The mention of 'safe-guarded for actions exceeding 50 entries' distinguishes it from the single entry update tool (timeiq_expense_update) and bulk delete tool (timeiq_expense_delete_many).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for bulk updates with a safeguard for large batches, but it does not explicitly state when to use this tool over alternatives or provide exclusions. The sibling tools (e.g., timeiq_expense_update) provide context for differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new draft invoice.
| Name | Required | Description | Default |
|---|---|---|---|
| client_id | Yes | ||
| invoice_number | Yes | ||
| date | No | ||
| due_date | No | ||
| notes | No | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It mentions creation of a draft invoice but fails to note side effects (e.g., whether it creates a persistent record immediately), required permissions, or the handling of the 'dry_run' parameter. This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. However, the extreme brevity comes at the cost of necessary detail, making it more under-specified than concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and the presence of six parameters (two required), the description fails to provide sufficient context. It does not explain the meaning of return values, the effect of 'dry_run', date formats, or any validation rules, leaving significant gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description does not explain any of the six parameters, including key ones like 'client_id', 'invoice_number', or 'dry_run'. The description adds no semantic value beyond what the schema provides, leaving the agent to guess parameter meanings and constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new draft invoice' clearly specifies the verb (create) and resource (draft invoice), distinguishing it from sibling tools like 'timeiq_invoice_get' or 'timeiq_invoice_send'. However, it lacks additional context that could further differentiate it from other create tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as 'timeiq_invoice_send' or 'timeiq_invoice_update'. It does not mention prerequisites, required states, or exclusions, leaving the agent without context for appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an existing invoice by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose side effects (e.g., irreversibility, cascading deletions, permissions required). A simple delete description is insufficient for safe usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just one sentence, but it sacrifices informativeness. It could be expanded slightly to cover key details without losing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with no output schema, the description lacks completeness. It does not mention what happens upon deletion, whether it is irreversible, or how to confirm success.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the parameters. Notably, the 'dry_run' parameter is not mentioned, leaving its purpose unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Delete' and the resource 'invoice by ID', which distinguishes it from other invoice-related tools like create, update, or list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. For example, it does not mention prerequisites (e.g., invoice existence) or conditions under which deletion is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get invoice export/PDF compile details (Client-side URL tag).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully convey behavioral traits. It ambiguously says 'Get ... details' but does not specify if this triggers a PDF compilation or merely retrieves an existing URL. There is no mention of side effects, authorization needs, or whether the operation is read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is too short, consisting of only one sentence that sacrifices clarity for brevity. It leaves important details unexplained, making it under-specified rather than efficiently concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one undocumented parameter, no output schema, and no annotations, the description is severely incomplete. It does not explain the return value (expected URL), behavior, or any side effects, leaving the agent with insufficient context to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'id' is not explained in the description. Schema description coverage is 0%, so the description must clarify what 'id' refers to (e.g., invoice ID, export ID). The description adds no meaning beyond the schema field name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get invoice export/PDF compile details', which specifies a clear verb and resource. It distinguishes from siblings like timeiq_invoice_get (which likely returns invoice data) by targeting export details. However, the parenthetical 'Client-side URL tag' is cryptic and could be clearer about what exactly is returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternative invoice tools like timeiq_invoice_get, timeiq_invoice_send, or others. There is no mention of prerequisites (e.g., an invoice must exist) or context for when export details are available.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a single invoice by its ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses no behavioral traits beyond basic operation. No mention of permissions, idempotency, error cases, or data returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, focused sentence with essential information. Front-loaded, no wasted words. Appropriate for simple get operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple retrieval tool, but no output schema and no mention of what fields are returned. Could briefly note typical response contents.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description adds no detail beyond 'by its ID'. Does not explain id format, constraints, or example values. Minimal added meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Get', resource 'invoice', and identifier 'by its ID'. Distinguishes from siblings like timeiq_invoice_list and timeiq_invoice_get_by_number.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use or when-not-to-use guidance. No mention of when to prefer this over timeiq_invoice_get_by_number. Lacks context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single invoice by its alphanumeric invoice number.
| Name | Required | Description | Default |
|---|---|---|---|
| number | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states the basic operation without disclosing behavioral traits like authentication needs, error handling for missing invoices, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, concise and to the point. No unnecessary words, making it easy to process.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Minimally adequate for a simple get-by-identifier tool. With no output schema, it doesn't explain return values or error cases. Could benefit from mentioning typical response structure or behavior if invoice not found.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description adds meaning by specifying the parameter as 'alphanumeric invoice number', which goes beyond the schema's generic 'string' type. However, it provides no further details on format or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Get), resource (single invoice), and method (by alphanumeric invoice number). It effectively distinguishes from sibling tools like 'timeiq_invoice_get' (likely by ID) and 'timeiq_invoice_list' (list all).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as 'timeiq_invoice_get' or 'timeiq_invoice_list'. There is no mention of when not to use it or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all invoices, optionally filtered by date range.
| Name | Required | Description | Default |
|---|---|---|---|
| from | No | ||
| to | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must fully disclose behavior. It only mentions listing and date filtering, omitting details like pagination, sorting, scope (e.g., includes deleted?), auth requirements, or rate limits. This is insufficient for safe autonomous invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 10 words that is front-loaded with the main purpose. No redundant information; every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (list operation, no output schema, many siblings), the description fails to mention return structure, default behavior, or selection criteria relative to sibling list tools. An agent lacks key context for correct selection and use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It clarifies that 'from' and 'to' are date-range filters, but does not specify date format (e.g., ISO 8601) or behavior when omitted. Basic meaning added, but format details missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists all invoices with optional date range filtering. It distinguishes from siblings like timeiq_invoice_get (single invoice) and timeiq_invoice_list_for_client (client-specific), making the tool's role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing invoices with optional filtering, but does not explicitly state when to use this tool over alternatives like timeiq_invoice_list_for_client or timeiq_billing_invoices. No when-not or exclusion criteria provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all invoices for a specific client within an optional date range.
| Name | Required | Description | Default |
|---|---|---|---|
| clientId | Yes | ||
| from | No | ||
| to | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It states it lists invoices (a read operation) but provides no details on ordering, pagination, date format, or response shape. This is insufficient for an agent to understand behavior beyond safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the core purpose. No extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters and no output schema or annotations. The description omits pagination, response fields, error handling, and date range constraints. For a list tool, this is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only mentions 'client' and 'optional date range' without specifying that clientId is a number or the expected format for from/to (likely ISO dates). The parameter semantics are vague.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list', the resource 'invoices', and the scope (for a specific client, optional date range). It distinguishes from sibling tools like 'timeiq_invoice_list' (all invoices) and 'timeiq_invoice_get' (single invoice).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (listing invoices for a client, optionally filtered by date), but does not explicitly mention alternatives or when not to use. It is clear but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark an invoice status as fully paid.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description lacks details on side effects, reversibility, or authorization requirements. It only states the action without explaining the resulting system state or any constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks necessary detail. While front-loaded with the action, it doesn't earn its place as it omits critical information beyond the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no output schema and no parameter descriptions, the description should provide more context about the effect of marking paid, any irreversible consequences, or expected behaviors. It is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not clarify the parameters. The 'id' parameter is not explained (presumably invoice ID), and the 'dry_run' parameter's purpose is missing. Since schema description coverage is 0%, the description must compensate, but it fails to do so.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: marking an invoice as fully paid. It distinguishes from sibling tools like 'timeiq_invoice_mark_unpaid' and 'timeiq_invoice_mark_written_off' by specifying the exact status change.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. There is no mention of prerequisites, such as the invoice needing to be unpaid, or scenarios where marking as paid is appropriate versus marking as written off.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a paid or drafted invoice status as unpaid.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It only states the status change but omits side effects (e.g., reversibility, impact on payment records) or constraints, leaving significant ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, but it is under-specified; it achieves conciseness at the expense of completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, no annotations, and zero parameter explanations, the description fails to provide essential context for a mutation tool—no indication of return values, error conditions, or impact on related data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 2 parameters (id, dry_run) with 0% description coverage. The description does not explain their meaning or purpose, forcing the agent to guess their roles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'mark' and the resource 'invoice status,' specifying it can change paid or drafted invoices to unpaid. This distinguishes it from sibling tools like timeiq_invoice_mark_paid or timeiq_invoice_mark_written_off.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or conditions (e.g., permissions, invoice state) that must be met.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark an invoice status as written-off/uncollectible.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description implies a write operation but does not disclose side effects, permissions, or reversibility. No annotations mitigate this.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise but under-specified. Lacks detail needed for effective use.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing info on return values, side effects, and parameter details. Incomplete for a mutation tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No description of parameters; dry_run and id are not explained. Schema coverage is 0%, so the description fails to add value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action: marking an invoice as written-off/uncollectible. It distinguishes from sibling tools like mark_paid and mark_unpaid.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Siblings like mark_paid and mark_unpaid exist but are not mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trigger the invoice-send email to the client's email addresses.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It only says 'Trigger the invoice-send email', implying an outbound email is sent, but fails to mention side effects (e.g., marking invoice as sent), reversibility, or that the dry_run parameter can be used for testing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no fluff, but it sacrifices necessary information. It is concise but incomplete.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and two parameters, the description should cover behavior and parameter purpose. It omits important context like the function of dry_run, what happens after sending, and any prerequisites. Incomplete for a low-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description should compensate by explaining parameters. It does not mention id (required) or dry_run (optional) at all, leaving their meaning entirely to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Trigger the invoice-send email'), resource (invoice), and recipient ('client's email addresses'). It is specific and distinguishes from sibling tools like timeiq_invoice_create or timeiq_invoice_update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. For example, it does not mention that the invoice must exist or have a client email address.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an invoice (e.g. details, dates, comments) with a partial changeset.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| changeset | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It states 'update' (mutation) and 'partial changeset' (PATCH semantics), but does not disclose potential side effects, validation rules, or requirements (e.g., invoice existence, authorization). The dry_run parameter is unexplained. For a mutation tool, this is minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no wasted words. It is concise and front-loaded with the main action. However, it could be slightly expanded to include parameter hints without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters (2 required), no output schema, and many sibling invoice tools, the description is incomplete. It does not explain the return value, error scenarios, or how dry_run works. For a mutation operation with zero annotations, this leaves significant gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It adds examples of changset fields (details, dates, comments) but does not explain the id parameter (assumed invoice ID) or the dry_run parameter purpose. While it adds some context beyond the bare schema, it is insufficient to fully understand all parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update'), the resource ('an invoice'), and the method ('partial changeset'). It provides examples ('details, dates, comments') which distinguishes it from sibling tools like create, delete, or mark_paid. The purpose is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for updating existing invoice fields with a partial changeset, but it does not explicitly contrast with sibling tools such as mark_paid or send. There is no guidance on when not to use it or prerequisites (e.g., invoice must exist). The mention of 'partial changeset' is a helpful hint but insufficient for clear decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a new line item details row to an existing invoice.
| Name | Required | Description | Default |
|---|---|---|---|
| invoice_id | Yes | ||
| description | Yes | ||
| quantity | Yes | ||
| rate | Yes | ||
| amount | No | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description only implies a write operation ('Add') but does not disclose potential side effects, required permissions, or whether the action is undoable. Minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence with 8 words; no unnecessary words. However, it sacrifices informativeness for brevity. Could be more structured without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and no description of return value or side effects. For a tool that modifies an invoice, the description lacks outcome details. Incomplete for a 6-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description adds no explanation of any parameters (e.g., what 'amount' vs 'rate' mean, purpose of 'dry_run'). With 6 parameters and high required count, the description should provide meaning but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('Add'), the resource ('line item details row'), and context ('to an existing invoice'). Distinct from siblings like timeiq_lineitem_delete and timeiq_lineitem_update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, no prerequisites or context given. Lacks explicit when/when-not usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a line item details row from an invoice.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only indicates a deletion operation, but with no annotations, it fails to disclose key behavioral traits such as error handling on nonexistent IDs, permission requirements, or side effects. The dry_run parameter is mentioned in the schema but not explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It is appropriately concise for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and lack of output schema, the description is insufficient. It does not explain how to obtain the 'id' or the effect of 'dry_run', leaving gaps for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and no parameter descriptions in the schema, the description adds no semantic meaning to the parameters 'id' and 'dry_run'. The agent must infer their purpose from the tool name alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Remove'), the resource ('a line item details row'), and the context ('from an invoice'). It effectively distinguishes this tool from its siblings like timeiq_lineitem_add and timeiq_lineitem_update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or exclusions. The agent is left to infer usage without explicit instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a single line item details row on an invoice.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| changeset | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only states 'Update', which implies modification, but does not disclose behavioral traits such as whether it is idempotent, what happens if the invoice is already finalized, error handling, or side effects. This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loading the key information. It is not verbose, but it sacrifices necessary detail for brevity. Every word earns its place, but it could include more context without becoming wordy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema, annotations, and parameter descriptions, the description should provide more context (e.g., what fields can be updated, how dry_run works). It only covers the general purpose, leaving the agent with significant gaps to infer behavior. This is insufficient for a tool with no additional structured information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 3 parameters with 0% schema description coverage. The description adds no specific meaning to parameters: it does not explain that 'id' is the line item ID, that 'changeset' is an object of fields to modify, or what 'dry_run' does. The description fails to compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Update' and the resource 'a single line item details row on an invoice'. This distinguishes it from sibling tools like timeiq_lineitem_add and timeiq_lineitem_delete. However, it does not specify what 'details' refers to or which fields can be updated, slightly reducing specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives, such as prerequisites or conditions (e.g., invoice must be editable). While the tool name implies it updates a line item, there is no contextual help for an AI agent to decide between this and other updates like timeiq_invoice_update.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dismiss/acknowledge a single notification by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose any behavioral traits (e.g., side effects, permissions, or whether this is a destructive action). With no annotations, the description carries full burden but is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with verb and object, no wasted words. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 2 parameters and no output schema, the description covers basic intent but lacks parameter descriptions and usage context, leaving the agent without full guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the description adds no meaning to the parameters 'id' (number, required) and 'dry_run' (boolean). It does not explain their purpose or valid values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'dismiss/acknowledge' and the resource 'single notification by ID', effectively distinguishing it from siblings like timeiq_notification_list which lists notifications.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives like timeiq_notification_list or other notification tools. Usage is implied but not elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List notifications for a team member within a date range.
| Name | Required | Description | Default |
|---|---|---|---|
| personId | Yes | ||
| start_date | Yes | ||
| end_date | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It only states it lists notifications, but fails to mention whether it is read-only, what happens when no notifications exist, or any other behavioral traits (e.g., order, pagination). The description is too minimal to give adequate transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that directly conveys the tool's purpose with no extraneous words. It is front-loaded with the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and output schema, and only 3 parameters with no schema descriptions, the description is too brief to provide a complete understanding. It lacks information on date format, personId type, potential constraints, and result details, making it insufficient for an agent to reliably invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% with no parameter descriptions. The description compensates slightly by linking 'team member' to personId and 'date range' to start/end dates, but it does not specify the format of date strings or the exact nature of personId (e.g., ID number vs email). This leaves significant ambiguity for the AI agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list', the resource 'notifications', and the scoping conditions 'for a team member within a date range'. This distinguishes it from sibling notification tools like timeiq_notification_dismiss and timeiq_notification_send_missing_time_reminder.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for fetching notifications but provides no explicit guidance on when to use versus alternatives or when not to use. Sibling context suggests it is for listing, not dismissing or sending, but no direct exclusion is stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trigger a daily missing-time notification reminder email for a team member.
| Name | Required | Description | Default |
|---|---|---|---|
| personId | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only says 'send a daily reminder email' without detailing side effects, idempotency, permissions, or scheduling behavior. It does not disclose if multiple invocations are safe or if it triggers an immediate email.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 10 words is concise, but lacks essential details about parameters and behavior, making it under-specified rather than efficiently informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 2 parameters, no annotations, and no output schema, the description does not cover enough context: it omits parameter explanations, functional intent (daily reminder for which day?), and expected outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 2 parameters (personId, dry_run) with 0% coverage. Description does not explain 'dry_run' or map 'personId' to 'team member'. No additional meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Trigger'), resource ('daily missing-time notification reminder email'), and target ('team member'), distinguishing it from siblings like timeiq_timesheet_send_reminder.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., timeiq_timesheet_send_reminder) or prerequisites. The context is implied but not specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-activate an archived team member (sets isActive to true).
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description partially compensates by stating the explicit effect (sets isActive to true) and implying it only works on archived members. However, it lacks details on permissions, side effects, 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is perfectly concise and front-loaded with the key information. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and no output schema or annotations, the description covers the basic purpose but leaves out critical context like parameter explanation, error cases, and output format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required parameter (slug) with no description, and the tool description does not explain what slug represents. With 0% schema description coverage, the description fails to add meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (re-activate), the resource (archived team member), and the effect (sets isActive to true), distinguishing it from its sibling tools like timeiq_person_archive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, no prerequisites or exclusions mentioned. The sibling list includes many tools but no comparison is made.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Archive a team member (sets isActive to false).
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral details. It discloses that the tool sets isActive to false, which is the key effect. However, it omits other potential behaviors like reversibility, permissions required, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with a single sentence that includes the core purpose and a clarifying parenthetical. It is well-structured and front-loaded, but could arguably include more detail without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (one parameter, no output schema), the description covers the essential purpose and effect. However, it does not address whether the archive operation is reversible, how it differs from delete, or any dependency requirements, leaving some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'slug' has no description in the schema, and the description does not clarify what the slug represents or any constraints. The context from the tool name and description implies it identifies the team member, but additional semantics are missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (archive a team member) and explicitly defines what it does internally (sets isActive to false), distinguishing it from siblings like timeiq_person_activate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives like timeiq_person_delete. It is clear that it is for archiving (deactivating) a person, but lacks context on prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new team member record (Admin only).
| Name | Required | Description | Default |
|---|---|---|---|
| firstName | Yes | ||
| lastName | Yes | ||
| Yes | |||
| timeZone | No | Europe/Berlin | |
| userLevel | No | user | |
| isActive | No | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only states it creates a record and is admin-only. It does not disclose any behavioral traits such as side effects, permissions beyond admin, or whether the record is immediately active. With no annotations, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only one sentence, but it lacks important details for a tool with 7 parameters. It is under-specified rather than concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters with no schema coverage, no output schema, and no annotations, the description is grossly incomplete. It does not cover error handling, parameter details, or return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no information about the 7 parameters, including required ones like firstName, lastName, email. With schema coverage at 0%, the description adds no value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new team member record, which distinguishes it from other person-related tools like person_activate or person_update. The verb 'create' and resource 'team member record' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes 'Admin only', indicating that only admins should use this tool. It provides clear context for who can use it, but does not mention when not to use it or alternatives for non-admins.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a team member record by their slug (Admin only).
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only mentions the admin requirement but does not disclose whether deletion is permanent, cascading, or if any confirmation is needed. For a delete operation, more behavioral details are necessary.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no fluff. It front-loads the action and resource, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and missing annotations, the description lacks completeness. It does not explain the dry_run parameter, return value, or potential side effects. The tool list shows many related person tools, but no contextual guidance is provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 2 parameters (slug, dry_run) with 0% description coverage. The description clarifies 'by their slug' for the slug parameter but does not mention dry_run or explain its purpose. This partial coverage leaves the agent guessing about the dry_run parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete'), the resource ('team member record'), and the requirement ('by their slug (Admin only)'). It distinguishes from sibling delete tools like timeiq_client_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes 'Admin only', providing clear context for when the tool can be used. However, it does not specify when not to use it (e.g., preferring archive) or mention alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single team member's record by their slug.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; the brief description only implies a read operation but omits details on authentication, error handling, or response structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single clear sentence with no unnecessary words, efficiently conveying the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter get tool, the description is adequate but lacks details on return value or error states, leaving some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds 'by their slug' which tells the agent the parameter's role, but does not explain slug format or provide examples, and schema has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Get) and resource (team member's record) with the identifier (slug), distinguishing it from list or create tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like timeiq_person_list or timeiq_person_get, and no prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List team members. Can filter by active, archived, managed, or managed_archived.
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | active |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only mentions listing and filtering, missing details like response format, pagination, or rate limits, leaving significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no extraneous information. Efficiently conveys core purpose and filtering capability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter, the description is adequate but missing output structure (e.g., array of person objects). Could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must add meaning. It merely lists the enum values already present in the schema without explaining their semantics (e.g., what 'managed' means), adding minimal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists team members and specifies available filters, distinguishing it from related tools like timeiq_person_get or timeiq_person_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use (listing team members with optional filters) but does not explicitly exclude alternatives or provide when-not-to-use guidance, though it is clear enough for a read operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve required daily working capacity (in seconds) for a person in a date range.
| Name | Required | Description | Default |
|---|---|---|---|
| personId | Yes | ||
| start_date | Yes | ||
| end_date | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states the retrieval operation, but does not disclose behaviors like what happens when no data exists, rate limits, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, 13 words, front-loading the action and resource. No unnecessary verbiage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description minimally covers what the tool does. It could specify that the date range is inclusive or clarify the meaning of 'daily working capacity' per day, but is adequate for a simple retrieval.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% (no parameter descriptions in schema). The description adds meaning to the return value (seconds) but not to the parameters themselves beyond their names, which are self-explanatory but lack format or constraint details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieve' and specific resource 'required daily working capacity (in seconds)' for a person and date range, distinguishing it from sibling tool `timeiq_person_required_time_set`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like `timeiq_person_required_time_set` or other person-related tools. Lacks context or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set or update a person's required working capacity (in seconds) for a date.
| Name | Required | Description | Default |
|---|---|---|---|
| personId | Yes | ||
| date | Yes | ||
| required_seconds | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states 'set or update', implying mutation. It fails to disclose what happens to existing values, the effect of the dry_run parameter, or any authorization requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no unnecessary words. It front-loads the core functionality and is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no output schema, and no annotations, the description is too minimal. It does not explain return values, error conditions, or the behavior of the optional dry_run parameter. The context is incomplete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must add meaning beyond parameter names. It only mentions 'seconds' already in required_seconds and provides no details on date format or the role of dry_run. This is insufficient for a tool with 4 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets or updates a person's required working capacity for a date, using specific verb 'set or update' and resource 'required working capacity'. It distinguishes this tool from sibling tools like timeiq_person_required_time_get and timeiq_person_update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as timeiq_person_update. It does not mention prerequisites, conflicts, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing team member's record by their slug (Admin only).
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| changeset | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions 'Update' implying mutation, but does not detail whether the update is partial or full replacement, what happens if changeset is empty, or any validation behavior. Minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence. It conveys the core purpose and a key constraint without any fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and three parameters with zero description, the tool is substantially under-documented. Missing details on changeset contents, dry_run behavior, and response structure make it hard for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no information about the parameters (slug, changeset, dry_run). It only mentions 'by their slug' but does not explain changeset format or dry_run purpose. Agent has no guidance beyond schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (update), resource (team member record), identifier (slug), and an access constraint (Admin only). It differentiates from sibling tools like person_create, person_delete, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Admin only' constraint is useful, but there is no guidance on when to use this tool versus similar ones like timeiq_person_update_preferences or timeiq_person_activate. No explicit when-to-use or when-not-to-use advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the acting user's own frontend preferences.
| Name | Required | Description | Default |
|---|---|---|---|
| preferences | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description indicates write operation ('Update') but does not disclose side effects, permissions beyond 'acting user', or behavior of dry_run parameter. With no annotations, more detail needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is direct and efficient with no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, no annotations, and minimal description leaves significant gaps: return value, effect of dry_run, allowed preference keys, and error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and description does not explain 'preferences' object structure or 'dry_run' semantics, leaving agent without meaningful guidance beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Update', resource 'frontend preferences', and scope 'acting user's own', distinguishing it from other person update tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like timeiq_person_update or other preference tools; not explicit about context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-activate an archived project (sets active to true).
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses mutation ('sets active to true') but lacks details on permissions, failure conditions, or prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with action, no redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose and effect but misses parameter documentation (slug meaning) and precondition (project must be archived). Adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only parameter 'slug' is not described in schema or description. Schema coverage is 0%, and description adds no meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'Re-activate' and resource 'an archived project', with explanation of effect ('sets active to true'). Distinguishes from sibling archive and other activate tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for reactivating archived projects but provides no explicit when-to-use, when-not, or alternatives. Sibling tools like timeiq_project_archive are intuitive, but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Archive an active project (sets active to false).
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description only mentions the effect on the 'active' field but does not disclose reversibility, side effects, or required preconditions (e.g., project must be active). For a mutation tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that efficiently communicates the core purpose. No extraneous information, though adding parameter context could justify a higher score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's simplicity (one parameter, no output schema), the description lacks essential context such as whether archiving is reversible, how it affects project visibility or billing, and the required initial state. The tool is a mutation with no annotations, so the description bears full responsibility for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'slug' has 0% schema description coverage. The description adds no meaning about what 'slug' represents or how to obtain it, leaving the agent without guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('archive') and the resource ('active project'), and explicitly defines the effect as setting 'active to false'. This distinguishes it from siblings like timeiq_project_activate, timeiq_project_delete, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like project_delete or project_update. The description only states what it does, not the context or prerequisites for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new project linked to a client.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| client_id | Yes | ||
| is_billable | No | ||
| budget_type | No | ||
| budget_total | No | ||
| active | No | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden of disclosing behavioral traits. It only states the creation action and client linkage but omits important details like side effects, permission requirements, whether it returns the created project, and the effect of fields like dry_run, budget_type, etc.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but severely under-specified for a tool with 7 parameters. It sacrifices completeness for brevity, making it inadequately informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, no output schema, no annotations) and the presence of many sibling tools, the description is far from complete. It fails to explain the purpose of optional fields, return values, or any constraints, leaving the agent with insufficient information to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only mentions 'linked to a client' but does not explain any of the 7 parameters, including required fields (name, client_id) or the meaning of budget_type, is_billable, etc. This adds no value beyond the schema's type names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new project and specifies it is linked to a client, using a specific verb and resource. This distinguishes it from sibling tools like update, archive, or delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., timeiq_project_update, timeiq_project_archive). It does not mention prerequisites such as the existence of a client_id, nor does it state 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.
Delete an existing project by its slug.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. While it implies destruction, it does not mention any side effects (e.g., cascading deletes), authorization needs, or the existence of a dry_run parameter that could preview the deletion. The omission of dry_run behavior is a notable gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, a single sentence that delivers the core purpose. It is front-loaded and efficient, though it sacrifices completeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (delete by slug with optional dry_run), the description fails to explain critical behavior like what a dry_run does, what happens on success/failure, or any constraints. It is insufficient for safe and effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. It explains the 'slug' parameter as identifying the project, but completely ignores the 'dry_run' parameter, leaving its purpose undocumented. Only partial value added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete'), the target resource ('an existing project'), and the identifier ('by its slug'). It is specific and distinguishes from siblings like timeiq_project_activate or timeiq_project_update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., timeiq_project_archive), no prerequisites (e.g., project must exist), and no caution about destructive effects. It simply says what it does without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single project by its slug.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits. It states it's a 'Get' operation, implying a read, but does not mention idempotency, error handling (e.g., slug not found), permissions, or any side effects. This is minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one sentence), which is concise, but it omits important details that would justify its brevity. It is not fully appropriate as it sacrifices completeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description should still specify what the tool returns (e.g., a project object) and any potential errors. It only states the retrieval mechanism, leaving the agent without a complete understanding of the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameter 'slug' is mentioned in the description ('by its slug'), but it adds no additional meaning beyond the schema (type string, required). No explanation of what a slug is, its format, or constraints. With 0% schema description coverage, the description should compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Get'), resource ('project'), and identifier ('slug'), which is sufficient for a simple retrieval tool. However, it does not explicitly mention what is returned (e.g., project details), which would add clarity, but the purpose is still clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like timeiq_project_list or timeiq_project_get. The description only states the action and parameter, leaving the agent without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List projects. Can filter by active, archived, managed, or managed_archived.
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | active |
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 does not disclose potential pagination, permissions, or other behavioral aspects beyond the filter options.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise and front-loaded, with two sentences that directly convey the tool's purpose and key feature.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, no output schema), the description is adequate. It could be improved by mentioning return format or pagination, but it is generally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description mentions the filter parameter and its options, adding some meaning beyond the schema. However, with 0% schema description coverage, it does not fully compensate for the lack of parameter details in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'projects', and by mentioning filter options, it distinguishes this listing tool from sibling tools that perform other operations on projects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly tells when to use the tool (to list projects with filters). It does not explicitly mention when not to use it, but the context of sibling tools provides clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing project by its slug with a partial changeset.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| changeset | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description only states 'Update' which implies mutation, and mentions 'partial changeset' but lacks details on behavior such as validation, idempotency, error handling, or required permissions. With zero annotations, the description should provide more context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, concise and front-loaded. Could be improved by adding a second sentence for usage or param details, but current length is appropriate for a simple update tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters, no output schema, no annotations, and sibling tools with similar names, the description is insufficient. Does not explain return value, behavior for invalid slug or changeset, or what dry_run does. An agent is left guessing about error states and dry-run functionality.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 3 params with 0% description coverage. Description mentions 'slug' (identification) and 'partial changeset' for the changeset parameter, which adds some meaning, but does not explain the 'dry_run' parameter. Also, changeset is an object with additionalProperties: {} – description does not clarify allowed fields. Incomplete coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Update', resource 'existing project', identification method 'by its slug', and scope 'partial changeset'. This distinguishes it from sibling tools like create, delete, get, list, and update_many.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for updating a single project partially, but no explicit guidance on when not to use or alternatives like update_many. Sibling tool list includes project_update_many, which could be confused. Lacks when-to-use vs 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.
Bulk update multiple projects. Safe-guarded for actions exceeding 50 entries.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | ||
| changeset | Yes | ||
| confirm_bulk | No | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description discloses a safeguard for actions exceeding 50 entries, but does not elaborate on what happens (e.g., requires confirm_bulk, reject, or warning). No annotations exist to clarify read/write nature or side effects. Changeset is loose (additionalProperties) without constraints. Partial transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no redundant information. Front-loaded with the main action and a key behavioral note. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite moderate complexity (4 params, nested object, no output schema), the description fails to explain return values, field constraints for changeset, or the role of optional parameters. The safeguard mention is positive but insufficient for complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 4 parameters with 0% description coverage. Description only mentions safeguard, not the purpose of ids, changeset, confirm_bulk, or dry_run. Agent cannot infer that changeset is a set of project fields or that confirm_bulk is needed for large batches. Minimal added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Bulk update multiple projects', clearly specifying the verb (bulk update) and resource (projects). Distinguishes from sibling timeiq_project_update (single) by emphasizing 'multiple'. Also mentions safeguard for >50 entries, adding scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage for bulk operations as opposed to single updates, but no explicit when-to-use or when-not-to-use. No mention of alternatives like timeiq_project_update or prerequisites. The safeguard hint provides some context but insufficient for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate classic summary report (legacy layout).
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | ||
| end_date | Yes | ||
| clients | No | ||
| projects | No | ||
| services | No | ||
| people | No | ||
| extras | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description gives no behavioral details. It does not disclose side effects (e.g., data modification, authorization needs), output format, pagination, or any constraints beyond generation. For a tool with no annotations, the description must cover behavior, but it fails entirely.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single 5-word sentence, which is concise but far from sufficient. It lacks structure and omits essential information. Under-specification is not virtue in this context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters, no output schema, and no annotations, the description is extremely incomplete. It provides no details on report content, filtering semantics, or expected output. An AI agent cannot determine how to correctly invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the 7 parameters. Crucial parameters like start_date, end_date, clients, projects, services, people, and extras are left unexplained. An AI agent cannot infer how to use these inputs effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: generate a classic summary report in legacy layout. The verb 'Generate' and resource 'classic summary report' are specific. However, it does not explain what the report contains, and among many report siblings (timeiq_report_standard, timeiq_report_time, etc.), the term 'classic' and 'legacy' provide some differentiation but not full clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not indicate when to use this tool versus other report tools (e.g., timeiq_report_standard, timeiq_report_time). There is no mention of prerequisites, contexts, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate classic time report.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | ||
| end_date | Yes | ||
| clients | No | ||
| projects | No | ||
| services | No | ||
| people | No | ||
| extras | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as side effects, authorization requirements, or output format. The description carries the full burden but fails to provide transparency beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the verb and resource. While concise, it is too brief to adequately inform the agent, lacking necessary detail for a tool with multiple parameters and sibling alternatives.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, no output schema, many sibling report tools, no annotations), the description is severely incomplete. It provides no information about the report's scope, filtering options, or output format, making it insufficient for reliable agent selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions for any of the 7 parameters, and the tool description adds no meaning beyond the schema. With 0% schema description coverage, the description should compensate but does not, leaving parameters entirely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Generate classic time report', which indicates a report generation task. However, it does not differentiate from the sibling tool 'timeiq_report_classic', potentially causing confusion. The purpose is clear but not distinctive enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'timeiq_report_classic' or 'timeiq_report_time'. The description lacks context on prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate custom report utilizing flexible filter extras.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | ||
| end_date | Yes | ||
| clients | No | ||
| projects | No | ||
| services | No | ||
| people | No | ||
| extras | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose key behaviors. It only says 'generate', implying creation but not whether it's read-only, destructive, or requires authentication. No mention of rate limits, side effects, or response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but lacks substance. It doesn't break down information or front-load key details, sacrificing clarity for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, nested objects, no output schema), the description is severely incomplete. It fails to explain return values, parameter usage, or how the 'extras' work, making it insufficient for effective tool use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% — none of the 7 parameters have descriptions. The description only mentions 'extras' vaguely, leaving start_date, end_date, clients, projects, services, and people completely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it generates a custom report with flexible filter extras, which is somewhat clear but vague. It does not specify what makes it custom versus other report tools like timeiq_report_classic or timeiq_report_standard, leaving ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus the many other report siblings. The description lacks context on prerequisites, alternatives, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate summary expense report.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | ||
| end_date | Yes | ||
| clients | No | ||
| projects | No | ||
| services | No | ||
| people | No | ||
| extras | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits like read-only nature, side effects, authentication needs, or output format. For a report tool, essential context like whether it modifies data is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise, but it lacks structure and essential details. It is under-specified rather than efficiently informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, nested objects, no output schema) and absence of annotations, the description is severely incomplete. It does not explain what the report contains, how filtering works, or what the output looks like.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 7 parameters with 0% description coverage, and the tool description adds no meaning or examples. Parameters like 'start_date', 'end_date', 'clients', etc. are left entirely undefined, making it impossible to infer their purpose from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Generate summary expense report,' which includes a clear verb and resource. However, it does not differentiate from sibling tools like 'timeiq_report_expenses_detail' or 'timeiq_report_standard_expenses,' missing a specific scope or distinguishing characteristic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'timeiq_report_expenses_detail' or other report tools. The description lacks any context about appropriate use cases or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate detailed expense-entry report (items list).
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | ||
| end_date | Yes | ||
| clients | No | ||
| projects | No | ||
| services | No | ||
| people | No | ||
| extras | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description does not disclose any behavioral traits such as data mutability, required permissions, or output characteristics. The agent has no insight beyond the basic generation action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very brief (one sentence), but it is under-specified rather than concise. It lacks critical details about parameters and behavior, so the brevity is detrimental.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters, required fields, and no output schema, the description is severely incomplete. It does not explain filtering, output format, or the 'extras' object, leaving large gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions (0% coverage), and the description does not explain any parameters. The agent cannot infer the meaning or usage of the 7 parameters, including required fields like start_date and end_date.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates a detailed expense-entry report as an items list. It distinguishes from sibling expense reports (e.g., timeiq_report_expenses, timeiq_report_standard_expenses) by specifying 'items list,' but does not explicitly contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not indicate when to use this tool versus other expense reports or alternative tools, nor does it mention prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Identify people with incomplete, un-submitted, or open timers.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | ||
| end_date | Yes | ||
| clients | No | ||
| projects | No | ||
| services | No | ||
| people | No | ||
| extras | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are entirely absent, so the description must fully disclose behavioral traits. It only states the tool identifies people but does not mention whether the tool is read-only, what the output format is, or any restrictions. For a reporting tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but poorly structured. It lacks any breakdown of usage, parameters, or output, making it minimally viable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters, 0% schema coverage, no output schema, and no annotations, the description is vastly incomplete. The agent cannot determine what the tool returns, how to format inputs, or what constraints apply.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 7 parameters with 0% description coverage. The description does not explain the meaning or format of any parameter, including required fields like start_date and end_date. This forces the agent to guess their purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool identifies people with incomplete, un-submitted, or open timers. It uses a specific verb ('identify') and resource ('people with...timers'), distinguishing it from sibling report tools that focus on different aspects of time reporting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like timeiq_report_missing_time or timeiq_report_time. There is no mention of prerequisites, exclusions, or comparative scenarios, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Identify people with missing required working hours (capacity gaps).
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | ||
| end_date | Yes | ||
| clients | No | ||
| projects | No | ||
| services | No | ||
| people | No | ||
| extras | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but fails to disclose behavioral traits like read-only nature, required permissions, or output format. The description only mentions identification without behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise but structure is minimal; no front-loading of key information. Adequate in size but under-specified for a complex report tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, and no annotations, the description is incomplete. It does not clarify return values, filtering behavior, or how results are presented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description does not explain any of the 7 parameters (e.g., start_date, end_date, clients). No meaning added beyond parameter names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool identifies people with missing required working hours (capacity gaps), which is a specific verb+resource. However, it does not explicitly differentiate from sibling tools like timeiq_report_incomplete_time or timeiq_notification_send_missing_time_reminder, which may have overlapping functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this tool versus alternatives such as timeiq_report_incomplete_time or timeiq_notification_send_missing_time_reminder. Lacks context on prerequisites or use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate payroll report (reconciled hours, rates, costs).
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | ||
| end_date | Yes | ||
| clients | No | ||
| projects | No | ||
| services | No | ||
| people | No | ||
| extras | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description does not disclose whether the tool is read-only, what side effects occur, or any permission requirements. As a report, it is likely non-destructive, but this is not stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence without wasted words, but it is too brief to be fully informative. It could add more detail without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, and many sibling tools, the description is insufficient. Missing parameter descriptions, output format, and usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain any parameters, including the required start_date and end_date, or the optional filters like clients, projects, and people.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it generates a payroll report with reconciled hours, rates, and costs. However, it does not differentiate it from sibling report tools like timeiq_report_classic or timeiq_report_time.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool compared to other report tools. No context for prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate report aligned to timesheet periods.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | ||
| end_date | Yes | ||
| clients | No | ||
| projects | No | ||
| services | No | ||
| people | No | ||
| extras | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits (e.g., data destruction, authentication needs, rate limits, or what 'aligned to timesheet periods' means in terms of data aggregation).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise and front-loaded, but it is under-specified. It earns its place but lacks necessary detail for effective use.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, no output schema, no annotations, many sibling report tools), the description is completely inadequate. It does not specify return values, filtering behavior, or how it aligns with timesheet periods.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%. The description does not explain any of the 7 parameters (start_date, end_date, clients, projects, services, people, extras). It only hints at date range via 'aligned to timesheet periods' but fails to add meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description 'Generate report aligned to timesheet periods' uses a specific verb ('Generate') and resource ('report') with a qualifier that differentiates it from other report tools like timeiq_report_classic. However, it does not explicitly distinguish from all siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool vs alternatives such as timeiq_report_classic or timeiq_report_standard. It lacks any when-not or alternative contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate feed showing recent activity/logs by project or person.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | ||
| end_date | Yes | ||
| clients | No | ||
| projects | No | ||
| services | No | ||
| people | No | ||
| extras | No |
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 disclosing behavioral traits. It only states the basic function — generating a feed — without explaining side effects, authorization needs, rate limits, or how the feed is returned (e.g., pagination, ordering). The description lacks critical operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 12 words, which is extremely concise. While brevity is valued, it comes at the expense of necessary detail. The description is not front-loaded with the most critical information; it is merely a minimal summary. It could be restructured to include key constraints upfront.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, no output schema, no annotations), the description is very incomplete. It does not specify output format (e.g., list of logs), date format requirements, whether parameters are exclusive or additive, or any default behavior. The agent would likely misinterpret how to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must add meaning to the parameters. It only mentions filtering 'by project or person', corresponding to the 'projects' and 'people' arrays. It does not explain 'start_date', 'end_date', 'clients', 'services', or 'extras', leaving the agent with insufficient guidance for proper usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates a feed of recent activity/logs, with filtering by project or person. It distinguishes from sibling reporting tools (e.g., timeiq_report_time, timeiq_report_expenses) by focusing on a 'feed' of recent activity, which is unique among the many report variants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention when not to use it, what other tools might be more appropriate (e.g., for detailed time reports), or any prerequisites (e.g., required permissions). The intended use case is only vaguely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perform filter search across all expense entries.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | ||
| end_date | Yes | ||
| clients | No | ||
| projects | No | ||
| services | No | ||
| people | No | ||
| extras | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It states 'filter search' but does not disclose whether it is read-only, how results are paginated or sorted, or what happens when no entries match. Behavioral traits are largely absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently short (one sentence) but lacks substance. It is not verbose, but conciseness should not come at the expense of completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters (2 required), no output schema, and no annotations, the description is severely incomplete. It does not explain how filtering works, what the response format is, or any usage constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description adds zero information about parameters. It does not explain the format or semantics of start_date, end_date, clients, projects, services, people, or extras.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('perform filter search') and resource ('expense entries'), and specifies scope ('all'). It effectively distinguishes from sibling tools like timeiq_report_expenses which likely generate reports, not filter searches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. Does not mention when not to use it or any prerequisites, such as requiring existing expense entries or date range constraints beyond required parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perform filter search across all time entries.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | ||
| end_date | Yes | ||
| clients | No | ||
| projects | No | ||
| services | No | ||
| people | No | ||
| extras | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description offers no behavioral details (e.g., read-only, pagination, rate limits, what results contain). The description is too minimal to assist an agent in safe use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only one short sentence, which is concise but lacks structure and fails to include necessary details about parameters, output, or usage context. It is under-specified for a tool with multiple optional filters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, 2 required, no output schema, and no annotations, the description is completely inadequate. It does not explain return values, date formats, or how to handle the extras object, leaving agents with insufficient information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 7 parameters with 0% description coverage, and the tool description does not add any meaning or format guidance beyond the raw schema. It fails to compensate for the lack of parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it performs a filter search across all time entries, which gives a basic purpose. However, it does not specify what fields are searched or differentiate it from sibling tools like timeiq_report_time or timeiq_report_classic_time.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. With many sibling report tools, explicit context or comparisons would be necessary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate standard summary report overview.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | ||
| end_date | Yes | ||
| clients | No | ||
| projects | No | ||
| services | No | ||
| people | No | ||
| extras | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden. It only says 'generate report,' with no mention of side effects, permissions, or whether it is read-only. This is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short but overly vague; it lacks substance and does not earn its place. Conciseness without clarity is insufficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, and no annotations, the description is woefully incomplete. It does not explain what the report contains, how filters work, or any constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description adds no meaning beyond the input schema; it does not explain any of the 7 parameters, their formats, or allowed values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Generate standard summary report overview,' which is a verb+resource, but it is vague and does not distinguish this tool from many sibling report tools like timeiq_report_classic or timeiq_report_custom.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any exclusions. Among numerous report siblings, this is a significant gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate standard report - expenses totals.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | ||
| end_date | Yes | ||
| clients | No | ||
| projects | No | ||
| services | No | ||
| people | No | ||
| extras | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must communicate behavioral traits. The description only says 'Generate standard report - expenses totals' without disclosing side effects (e.g., data modification), output format, or any constraints. It is insufficient for safe usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (one phrase), but it lacks structure and details. It is concise but at the expense of utility. A longer description with key details would be more helpful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 7 parameters, no annotations, and no output schema, the description is incomplete. It does not explain the output format, date range interpretation, or whether filtered parameters are inclusive. It fails to provide a complete picture for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the tool description adds no meaning to parameters. The property names like 'clients', 'projects' are self-explanatory, but the description does not clarify expected formats, required options, or how filters combine. For a tool with 7 parameters, this is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Generate standard report - expenses totals' clearly states a verb (generate) and resource (standard report for expenses totals). It implies it produces totals, but it does not differentiate among sibling expense report tools like timeiq_report_expenses and timeiq_report_expenses_detail, leaving ambiguity about what 'standard' means.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus other expense report tools. There is no mention of prerequisites, alternatives, or exclusions, which is problematic given the variety of sibling reports.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate standard report - time totals and items.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | ||
| end_date | Yes | ||
| clients | No | ||
| projects | No | ||
| services | No | ||
| people | No | ||
| extras | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not disclose behavioral traits such as whether the report is read-only, caching behavior, or any side effects. The description is too brief to convey important constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which makes it concise but also too brief for a tool with 7 parameters. It lacks structure and essential details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high parameter count, no schema descriptions, no output schema, and many sibling report tools, the description is severely incomplete. It fails to explain what the report contains, how to filter, or the output format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description does not explain any parameter meanings or usage. Terms like 'clients', 'projects', 'services', and 'extras' are left undefined, forcing the agent to guess.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Generate standard report - time totals and items' which clearly indicates the action and content. However, it does not differentiate from sibling tools like timeiq_report_standard or timeiq_report_time, which might have overlapping functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus the many other report tools. The description lacks context about stuitable scenarios or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate time report (totals & project breakdowns).
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | ||
| end_date | Yes | ||
| clients | No | ||
| projects | No | ||
| services | No | ||
| people | No | ||
| extras | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral transparency. It only states 'Generate time report,' failing to disclose whether the tool is read-only, what side effects exist, or any output details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise but under-specified. A single vague sentence does not earn its place, as it lacks important contextual information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, and many sibling tools, the description is incomplete. It fails to explain filtering, output format, or how this report differs from others.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should explain parameters but does not. It provides no details on date formats, meaning of clients/projects/services/people arrays, or the extras object.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates a time report with totals and project breakdowns, providing a specific verb and resource. However, it does not differentiate from many sibling report tools like timeiq_report_classic_time or timeiq_report_time_detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not indicate when to use this report versus other report tools, nor does it mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate detailed time-entry report (specific items list).
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | ||
| end_date | Yes | ||
| clients | No | ||
| projects | No | ||
| services | No | ||
| people | No | ||
| extras | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden to disclose behavioral traits. It only says 'generate report', implying a read operation, but does not explicitly state it is non-destructive, nor does it mention side effects, authentication needs, or rate limits. For a report tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single 8-word sentence, which is overly terse given the complexity of 7 parameters and nested objects. While it is front-loaded, it sacrifices necessary detail for brevity, making it insufficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations, output schema, and any parameter descriptions, the description is severely incomplete. It does not explain the report's output structure, filter behavior, or how the parameters interact, leaving critical gaps for an AI agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 7 parameters with 0% description coverage, yet the description adds no explanations for any parameter (e.g., start_date, end_date, clients, projects, services, people, extras). The description fails to compensate for the lack of parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool generates a 'detailed time-entry report (specific items list)', which is a specific verb+resource. However, among many sibling report tools (e.g., timeiq_report_time, timeiq_report_classic, timeiq_report_expenses_detail), it does not clearly differentiate beyond the vague 'specific items list' hint. The purpose is clear but lacks distinctiveness.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternative report tools or other time-related tools. There is no mention of prerequisites, filters, or use cases, leaving the agent without context to choose appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Activate a previously archived service (sets isActive to true).
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must fully disclose behavior. It mentions setting isActive to true, but omits side effects, permissions, error conditions, or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, but it could be better structured to include parameter information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description lacks return value info, error conditions, and prerequisites, making it incomplete for a state-changing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and description adds no explanation for the required parameter 'slug' (e.g., what it represents or how to obtain it).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (activate) and the resource (service), and uniquely distinguishes from sibling tools like timeiq_service_archive by specifying the change to isActive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for activating an archived service, but lacks explicit guidance on when not to use, prerequisites (e.g., service must exist and be archived), or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Archive a service (sets isActive to false).
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the core behavior (sets isActive to false) but lacks details on reversibility, permissions, side effects, or error states. With no annotations, more context would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that conveys the essential information without any redundant text. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with no output schema and low schema coverage, the description omits return value, success/failure indicators, and preconditions (e.g., service must exist). Incomplete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain the 'slug' parameter at all. Schema coverage is 0%, so the description carries full responsibility and fails to add any meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action ('archive') and the effect ('sets isActive to false'), distinguishing it from sibling tools like timeiq_service_activate or timeiq_service_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, no prerequisites (e.g., service must exist), and no context on when archiving is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Activate a previously archived service category (sets isActive to true).
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the core behavior (setting isActive to true) but does not mention potential side effects, permissions, or whether the operation is idempotent. The description is adequate for a simple mutation but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence of 10 words with no filler or redundancy. Every word contributes to the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool simplicity (1 param, no output schema, no annotations), the description covers the basic action but lacks context on prerequisites (category must be archived), error cases (e.g., already active), and return value. It is minimally complete but could be more informative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description adds no explanation for the 'slug' parameter beyond what the schema provides. With a single parameter and no enums, the description should ideally clarify what 'slug' refers to (e.g., 'The unique identifier of the service category') but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Activate' and the resource 'previously archived service category', specifying the effect (sets isActive to true). This distinguishes it from sibling tools like timeiq_service_category_archive (which deactivates) and other service category tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that the tool should be used only on archived service categories, but does not explicitly state when to use it versus alternatives (e.g., use create for new categories) or provide any exclusions. No explicit guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Archive a service category (sets isActive to false).
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Although no annotations are provided, the description explicitly states that the tool sets isActive to false, making the mutation behavior clear. It does not mention side effects or permissions, but the stated effect is sufficient for a simple archive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence. However, it could briefly mention the parameter without harming conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, 0% schema coverage, and no output schema, the description is too terse. It does not provide enough context for correct invocation, especially lacking parameter explanation and any behavioral caveats.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain the 'slug' parameter or how to obtain it, despite 0% schema description coverage. The agent is left guessing the required identifier's nature or source.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Archive' and the resource 'service category' with a specific effect 'sets isActive to false'. It distinguishes from sibling activate tools (e.g., timeiq_service_category_activate) by indicating it sets isActive to false instead of true.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like delete or activate. There is no mention of prerequisites or conditions (e.g., does the category need to be inactive first?).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new service category.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| isActive | No | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as required permissions, idempotency, or side effects (e.g., creation behavior for duplicate names).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no extraneous words, but lacks any structural elements like parameter documentation or usage context. It is concise but incomplete.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, no annotations, and 3 parameters (including a dry_run flag), the description should explain parameters and return value. It does neither, leaving agents under-informed for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage for parameters (name, isActive, dry_run). The tool description does not explain the meaning or purpose of any parameter, so the agent gets no value beyond the schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new service category' clearly states the verb (Create) and resource (service category), and distinguishes from siblings that activate, archive, delete, list, or update categories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like list, update, or activate. No context on prerequisites or use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an existing service category by its slug.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
As a destructive operation with no annotations, the description should disclose irreversible effects, ownership requirements, or cascading impacts. It only states 'delete' without any behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the core action. It could be expanded slightly without losing conciseness, but there is no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool, the description should cover the dry_run parameter, return values, and side effects. It lacks these details, making it incomplete for an agent to use confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description only clarifies the required 'slug' parameter implicitly. The optional 'dry_run' parameter is not explained, and with 0% schema coverage, the description fails to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'delete', the resource 'service category', and the identifier 'by its slug'. This is specific and distinguishes the tool from sibling tools like create, list, and update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus other delete tools (e.g., timeiq_service_delete). There is no context about prerequisites, consequences, or whether alternatives exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List active service categories. Optional toggle to list archived categories instead.
| Name | Required | Description | Default |
|---|---|---|---|
| archived | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries the burden. It reveals the default behavior (active) and toggle (archived), but does not disclose authentication needs, rate limits, or return format. This is minimal but sufficient for a simple list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that conveys the entire purpose in a front-loaded manner. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter, the description is adequate. It could mention that the result is a list of category objects, but the absence of an output schema makes this a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for the 'archived' boolean, but the description explains its role as a toggle between active and archived categories. This adds significant value beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists service categories, with a default of active categories and an optional toggle for archived ones. Among siblings with similar list functions, this distinguishes by resource type and the toggle feature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like timeiq_expense_category_list or timeiq_service_category_* tools. No contextual or when-not-to-use information is included.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing service category by its slug with a partial changeset.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| changeset | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose side effects, permissions, and behavior on missing slug. It only says 'update', which implies mutation but lacks details on idempotency, error states, or effects of dry_run.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no filler. Efficient and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 3 parameters (one unstructured object), no output schema, and no annotations, the description is too sparse. An agent cannot determine valid changeset fields or expected response, making invocation risky.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description should compensate. It mentions 'slug' and 'partial changeset' but does not explain the structure of changeset or the role of dry_run. Minimal value beyond parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update', the resource 'service category', the identifier type 'by its slug', and the nature 'partial changeset'. This distinguishes it from sibling tools like create or delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use vs alternatives, prerequisites (e.g., category must exist), or when not to use. The description assumes knowledge of context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new service (task type).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| isBillable | No | ||
| isActive | No | ||
| service_category_id | No | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description does not disclose any behavioral traits such as idempotency, authentication requirements, side effects, or error scenarios. The description is insufficient for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. However, it is too brief for the complexity of the tool, sacrificing completeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and no output schema, the description is insufficient. It does not explain the creation process, required permissions, or return value, making the tool harder to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds no meaning to the five parameters. It does not explain what 'isBillable', 'isActive', 'service_category_id', or 'dry_run' mean, leaving the agent uninformed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new service (task type). It uses a specific verb 'Create' and resource 'service', and it is easily distinguishable from sibling tools like timeiq_service_list or timeiq_service_update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not indicate when to use this tool versus other service tools, nor does it mention prerequisites or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an existing service by its slug.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description lacks behavioral details. It does not indicate whether the deletion is permanent, cascading, or reversible. The agent cannot assess risk.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but omits relevant information about the dry_run parameter and behavioral context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations, output schema, and parameter descriptions, the tool description is too minimal. It fails to specify return values, error states, or dry_run behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description mentions 'slug' as the identifier but does not explain the 'dry_run' parameter or its effect. Incomplete compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete'), the resource ('existing service'), and the identifier ('by its slug'). This distinguishes it from sibling tools like create, update, or list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use delete versus alternatives such as archive or deactivate. No context about prerequisites or consequences.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List active services (task types). Optional toggle to list archived services instead.
| Name | Required | Description | Default |
|---|---|---|---|
| archived | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden. It states a read operation (list) but does not disclose pagination, permissions, or output format, which is adequate for a simple list tool but lacks full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 12 words, front-loaded with the main action, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and lack of output schema, the description covers the basic purpose and parameter but could be more complete by mentioning the return type (list of service objects).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to the 'archived' parameter by explaining it toggles to archived services, compensating for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List active services (task types)' with an optional toggle for archived services, using a specific verb-resource pair and distinguishing from sibling tools like timeiq_service_activate and timeiq_service_archive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions an optional toggle for archived services, implying when to use the parameter, but does not explicitly compare to alternatives like timeiq_service_get for details or timeiq_service_category_list for categories.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing service by its slug with a partial changeset.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| changeset | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description only discloses that it performs a partial update, but omits details on permissions, side effects, or response format. With zero annotations, the description should compensate more.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with purpose. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, no annotations, and 3 parameters (one nested object with unknown structure), the description fails to provide enough context for correct usage. Missing details on changeset properties, dry_run behavior, and return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning by identifying 'slug' as the identifier and 'changeset' as the partial update payload, but does not explain what fields changeset can contain or what 'dry_run' does. Schema has 0% description coverage, so both fall short.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (update), resource (service), identifier (by its slug), and the approach (partial changeset). It distinguishes itself from create, delete, and activate/archive siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. For example, it doesn't mention that for full replacement you might need a different tool or that activate/archive are separate operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get tenant-wide settings (features, billing defaults, locking rules).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the tool is read-only and what data it retrieves, but lacks details like rate limits, caching, or response structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with action and resource. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter getter, description is adequate. However, no output schema exists and description doesn't indicate return format, which would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist (schema coverage 100%). Baseline of 4 applies since description adds no parameter info but none needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Get' and resource 'tenant-wide settings', listing example categories (features, billing defaults, locking rules). Distinguishes from siblings like timeiq_settings_update (write) and timeiq_billing_info (specific billing settings).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage for retrieving settings, but no explicit when-to-use or alternatives mentioned. Sibling context helps differentiate, but description itself offers no guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all standard IANA timezones supported by TimeIQ.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It only says 'List' without mentioning that the tool is read-only, idempotent, or whether it returns cached data. Missing details like 'This operation is safe and does not modify data.'
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It efficiently conveys the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters or output schema, the description is adequate but could be more complete. It does not explain the return format (e.g., list of timezone strings) or any limitations like maximum count.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so no parameter descriptions are needed. The baseline score is 4 because schema coverage is 100% and there is nothing else to describe.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('all standard IANA timezones supported by TimeIQ'). It is specific and distinguishes from sibling tools, which focus on CRUD operations for clients, projects, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. While siblings are distinct, the description does not mention any prerequisites or context like 'Use to fetch supported timezones for time entry creation.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update tenant-wide configuration settings with a partial changeset (Admin only).
| Name | Required | Description | Default |
|---|---|---|---|
| changeset | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It indicates mutation ('Update') and authorization ('Admin only'), but does not disclose side effects, what gets overwritten, rate limits, or response behavior. Limited behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the main action and constraints. No unnecessary words, efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 2 parameters, no output schema, and no annotations, the short description is insufficient. It omits return values, error handling, valid changeset fields, and behavior of dry_run. Lacks completeness for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% for parameter descriptions. The description adds only 'partial changeset', which is vague. It does not explain what the changeset object should contain or the purpose of dry_run. Minimal added meaning beyond schema structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update', the resource 'tenant-wide configuration settings', and includes qualifiers 'partial changeset' and 'Admin only'. It distinguishes from siblings like timeiq_settings_get and timeiq_settings_timezones.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Admin only', which implies who should use it, but does not explicitly state when to use or when not to use, nor does it provide alternatives. Usage is implied but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perform batch week-grid row changesets (week grid editor).
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | ||
| batch | Yes | ||
| dry_run | No | ||
| requesting_slack_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It only states it performs changes, implying mutation, but provides no details about side effects, permissions, or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, 8 words, is concise but overly terse for a tool with 4 parameters. It does not provide enough information to justify its brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters, no schema descriptions, no output schema, and no annotations, the description is grossly inadequate. No details about what the batch array should contain, dry_run behavior, or return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameters (date, batch, dry_run, requesting_slack_id). The term 'batch' is hinted but not defined.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it performs batch week-grid row changesets, implying a batch operation on week-grid rows. It distinguishes from siblings like timeiq_time_create (single entry) and timeiq_time_delete, but the term 'changesets' is somewhat vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like single entry creation or deletion. No context about week-grid editor or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new time entry. Must provide either a start_time/end_time pair OR a duration (in minutes).
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | ||
| project_id | Yes | ||
| start_time | No | ||
| end_time | No | ||
| duration | No | ||
| notes | No | ||
| is_billable | No | ||
| service_id | No | ||
| timeZone | No | ||
| dry_run | No | ||
| requesting_slack_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states the purpose and a parameter constraint, but fails to disclose side effects (e.g., does it check for overlaps? Does it support multiple entries per day?), required permissions, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, making it concise but lacking structure. Given the tool's complexity (11 parameters), more information is needed. The sentence earns its place but doesn't cover enough.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, no annotations, and a complex set of parameters, the description is incomplete. It omits return values, error scenarios, and parameter formatting details, leaving significant gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% (11 parameters, none described in schema). The description only explains the mutual exclusion between start_time/end_time and duration, ignoring other parameters like date, project_id, notes, is_billable, service_id, timeZone, dry_run, requesting_slack_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new time entry' with a specific verb and resource. It distinguishes from siblings like timeiq_time_update or timeiq_time_batch by mentioning the constraint of providing either start_time/end_time pair or duration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description only provides the mutual exclusion constraint for parameters but offers no guidance on when to use this tool versus siblings like timeiq_time_create_overbook or timeiq_timer_start. No when-not-to-use or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a time entry that might exceed the project budget, and get immediate budget usage feedback.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | ||
| project_id | Yes | ||
| start_time | No | ||
| end_time | No | ||
| duration | No | ||
| notes | No | ||
| is_billable | No | ||
| service_id | No | ||
| timeZone | No | ||
| dry_run | No | ||
| requesting_slack_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions budget feedback, but omits important details like the effect of 'dry_run', required permissions, and whether the action is actually destructive (it creates a time entry).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but its brevity sacrifices necessary detail. It is efficient but could benefit from a more structured format listing key parameters or behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 parameters, no output schema, and no annotations, the description leaves significant gaps. It does not explain required parameters, the return format, or how to properly use the tool for testing with 'dry_run'. The agent lacks sufficient context to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no explanation for any of the 11 parameters, such as 'dry_run', 'timeZone', or 'requesting_slack_id'. It fails to clarify what parameters do beyond their names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a time entry' with a specific purpose: overbook budget and get immediate feedback. This distinguishes it from siblings like timeiq_time_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when budget might be exceeded and feedback is desired, but does not explicitly contrast with alternatives like timeiq_time_create or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an existing time entry by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| dry_run | No | ||
| requesting_slack_id | No |
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 fails to disclose behavioral traits such as whether deletion is permanent, if cascading effects occur, or required permissions. The description is minimal and does not add context beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the purpose. While efficient, it could include additional context without becoming overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema, annotations, and parameter descriptions, the description is incomplete. It does not inform the agent about return values, idempotency, or side effects, which are important for correct tool use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description adds no meaning beyond the parameter names. It does not explain the purpose of 'dry_run' or 'requesting_slack_id', leaving the agent without crucial context for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete an existing time entry by ID', specifying the verb (Delete), resource (time entry), and identifier (by ID). This differentiates it from sibling tools like timeiq_time_delete_many which delete multiple entries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for deleting a single time entry by ID, but provides no explicit guidance on when to use this tool over alternatives like timeiq_time_delete_many, nor any prerequisites or restrictions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete multiple time entries at once. Safe-guarded for actions exceeding 50 entries.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | ||
| confirm_bulk | No | ||
| dry_run | No | ||
| requesting_slack_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must disclose behaviors. It mentions a safeguard but does not explain what happens when the limit is exceeded, whether confirm_bulk is required, or if the deletion is permanent. Missing auth requirements, rate limits, and return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (12 words), but it underspecifies the tool's behavior. It is front-loaded but lacks structure and detail for a 4-parameter tool. Conciseness is not a virtue when it omits critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of sibling tools for single delete, batch update, and expense delete, the description lacks context about when to use this tool. No output schema, no parameter descriptions, and no mention of return values or error conditions. Incomplete for effective selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should clarify parameter meaning. It only alludes to the safeguard (likely confirm_bulk), but does not explain dry_run (test mode) or requesting_slack_id (audit). The description adds minimal value beyond param names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete'), resource ('multiple time entries'), and a key feature ('safe-guarded for actions exceeding 50 entries'). It differentiates from siblings like timeiq_time_delete (single) and timeiq_expense_delete_many (different resource).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates it is for bulk deletion with a safeguard, but does not explicitly state when to prefer this over timeiq_time_delete or timeiq_time_batch. No exclusions or alternatives are provided, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List time entries for the acting user within a given date range. Defaults to today.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | No | ||
| end_date | No | ||
| requesting_slack_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full burden. It states 'List', implying a read-only operation, but lacks details on authentication, error handling, or result format. For a simple list tool, this is adequate but could be improved.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no extraneous words. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite low complexity and no output schema, the description omits details about the requesting_slack_id parameter and does not explain output format or edge cases. It is marginally complete for the tool's purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only mentions 'date range' without defining start_date, end_date, or requesting_slack_id. It adds minimal value over the schema for parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'time entries for the acting user', and specifies the scope 'within a given date range'. It distinguishes from sibling tools like timeiq_time_list_person.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Defaults to today', providing context for default behavior. It implies usage for the acting user's own entries, but does not explicitly state when not to use or mention alternatives like timeiq_time_list_person.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List time entries for a specific person by their slug within a date range (Admin only).
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| start_date | Yes | ||
| end_date | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only indicates a read operation with admin access, but fails to mention return format, pagination, sorting, or error handling. For a list tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence of 15 words. Every word is meaningful, with no redundancy or extraneous detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and annotations, the description is too brief. It omits the output structure, pagination behavior, sorting, and any edge cases. For a list tool, this leaves the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains slug as 'by their slug' and dates as 'within a date range', adding context. However, it does not specify date format, slug meaning, or parameter constraints beyond required status.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list), resource (time entries for a person), and key parameters (slug for person, date range). It also notes the admin restriction, making it distinct from siblings like timeiq_time_list_me.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use when you need to list time entries for a specific person as an admin. It does not explicitly name alternatives or exclusions, but the admin-only note implies who should use it and contrasts with self-listing tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel the currently running stopwatch timer without creating a time entry.
| Name | Required | Description | Default |
|---|---|---|---|
| dry_run | No | ||
| requesting_slack_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals that no time entry is created upon cancellation, which is helpful. However, with no annotations, it does not disclose what happens if no timer is running, whether confirmation is needed, or any other side effects. The dry_run parameter is unexplained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that directly conveys the purpose without any superfluous words. It is optimally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations, output schema, and parameter descriptions, the description fails to provide a complete picture. It covers the action but not the input semantics, error conditions, or behavioral expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description offers no explanation for the two parameters (dry_run, requesting_slack_id). The agent cannot determine their purpose or usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (cancel) and the resource (currently running stopwatch timer) and adds a key behavioral nuance (without creating a time entry). It is specific but does not explicitly distinguish it from the sibling tool timeiq_timer_stop, which might have a different effect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like timeiq_timer_stop or timeiq_timer_start. It does not mention prerequisites for its invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the current running stopwatch timer for the acting user.
| Name | Required | Description | Default |
|---|---|---|---|
| requesting_slack_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations to indicate read-only or destructive behavior, and the description does not disclose behavioral traits such as what happens if no timer is running, error conditions, authentication requirements, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that is concise. However, it could include more detail without sacrificing brevity, such as the parameter's role or return behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and annotations, the description is incomplete. It does not specify return format, error handling, or prerequisites, which are important for the 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.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'requesting_slack_id' has no description in the schema (0% coverage) and the tool description does not explain its purpose, leaving ambiguity about whether it is used to fetch another user's timer despite the description saying 'for the acting user.'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieve' and the resource 'current running stopwatch timer for the acting user,' distinguishing it from sibling timer tools like start, stop, cancel, update, and update_entry.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not specify when to use this tool versus alternatives (e.g., timeiq_timer_get vs. timeiq_timer_list or other retrieval tools), nor does it mention prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a new stopwatch timer for a project.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| date | No | ||
| start_time | No | ||
| notes | No | ||
| service_id | No | ||
| is_billable | No | ||
| timeZone | No | ||
| dry_run | No | ||
| requesting_slack_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose all behavioral traits, but it only says 'start a timer.' It omits side effects (e.g., stopping an existing timer), permission requirements, or that dry_run is for testing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but sacrifices necessary detail for a tool with 9 parameters. It is front-loaded but inadequate for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters, no schema descriptions, no annotations, and no output schema, the description is severely incomplete. It fails to cover common usage scenarios, parameter constraints, or expected behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no meaning to any of the 9 parameters. Parameters like date, start_time, notes, dry_run are left unexplained, leaving the agent to guess their purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Start'), the resource ('stopwatch timer'), and the context ('for a project'). It distinguishes itself from sibling tools like stop, cancel, get, update by specifying 'start'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., manual time entry via time_create). No mention of prerequisites, such as requiring an active project or whether starting a timer stops others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop the currently running stopwatch timer and record the time entry.
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | ||
| dry_run | No | ||
| requesting_slack_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states it stops and records, but does not specify what happens if no timer is running, whether permissions are needed, or what side effects occur. The description is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 9 words, front-loaded with the action. It is extremely concise with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three optional parameters and no output schema, the description lacks essential details. It does not explain what dry_run does, what the return value is, or how to handle errors. The agent is left with significant ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the three parameters (notes, dry_run, requesting_slack_id). The agent has no information about their meaning or usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (stop), the resource (currently running stopwatch timer), and the effect (record the time entry). It distinguishes from sibling tools like timeiq_timer_cancel by implying that this tool records the entry, whereas cancel might discard it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives like timeiq_timer_cancel or timeiq_timer_update. It does not mention prerequisites (e.g., timer must be running) or contexts where it is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the configuration or start time of an active timer.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| changeset | Yes | ||
| dry_run | No | ||
| requesting_slack_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits. It implies mutation but does not explain side effects, required permissions, or behavior when the timer is not active. The phrase 'of an active timer' hints at a condition but is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but it sacrifices essential detail for brevity. It is not well-structured or front-loaded with critical information; every sentence does not earn its place as it omits significant context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 0% schema coverage, no output schema, and a complex changeset parameter, the description is severely incomplete. It fails to explain the changeset structure, the dry_run flag, or the requesting_slack_id purpose. The tool's behavior and interface remain largely undefined for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no meaning to the four parameters (id, changeset, dry_run, requesting_slack_id). The changeset object lacks constraints, and no parameter roles are explained. The agent is left with no guidance on how to populate these fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and the resource 'active timer', specifying that it updates configuration or start time. It distinguishes from sibling tools like timeiq_timer_start and timeiq_timer_stop, but does not explicitly differentiate from timeiq_timer_update_entry.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor are any prerequisites (e.g., timer must be active) or conditions for use mentioned. The description lacks context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the underlying time entry linked to an active timer.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| changeset | Yes | ||
| dry_run | No | ||
| requesting_slack_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description does not disclose behavioral traits like side effects on the timer, prerequisites (e.g., timer must be active), or whether the operation is reversible. For a state-modifying tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks structure. It does not front-load critical information beyond the basic action. Conciseness is acceptable, but the content is minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema, param descriptions, and behavioral details, the description is severely incomplete. A developer cannot use this tool correctly without additional documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description adds no information about the parameters. 'changeset' is an open-ended object without field guidance, and 'dry_run' and 'requesting_slack_id' are unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the specific resource ('underlying time entry linked to an active timer'). It distinguishes from sibling tools like 'timeiq_timer_update' (timer itself) and 'timeiq_time_update' (general time entries).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as when the timer is not active or when to use 'timeiq_time_update' instead. The description lacks usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Approve a submitted timesheet (Manager/Admin only).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It only states the role restriction and action, but does not disclose behavioral effects such as status changes or notifications, nor any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently communicates the core action and role restriction without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, and the presence of sibling tools, the description is incomplete. It does not explain the effect of the dry_run parameter, the result of approval, or any prerequisites, leaving gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the parameters. The 'id' parameter is not described (e.g., what it refers to), and 'dry_run' is not explained, so the agent gains no additional meaning from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action (approve) and the object (submitted timesheet), and includes a role restriction (Manager/Admin only), which clearly distinguishes it from sibling tools like decline or submit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions who can use the tool, but does not provide guidance on when to use it versus alternatives (e.g., approve vs decline), nor does it mention prerequisites like the timesheet must be in a submitted state.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the timesheet covering a specific date.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits but only states it gets a timesheet. Missing details like required permissions, return format, or any side effects 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at one sentence, but lacks structure (e.g., sections) that could improve clarity for a tool with many siblings.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and no output schema, the description is too minimal. It does not explain what the timesheet contains, whose timesheet it returns, or any limitations, leaving significant gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'date' has no schema description (0% coverage), and the description adds no format or validity information beyond restating the parameter name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get the timesheet covering a specific date,' with a specific verb and resource. Among many timesheet-related siblings, this distinguishes itself by focusing on retrieval by a single date.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like timeiq_timesheet_get or timeiq_timesheet_list. There is no mention of prerequisites, context, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Decline/reject a submitted timesheet (Manager/Admin only).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It reveals the mutation action but lacks details on consequences, irreversibility, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one sentence), but it omits essential parameter details. It is not overly verbose but sacrifices completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple operation and lack of output schema, the description should at least cover parameter semantics. It fails to provide enough context for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not explain any parameters. The agent gets no insight into the meaning of 'id' or 'dry_run'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Decline/reject' and the resource 'submitted timesheet', distinguishing it from sibling tools like timeiq_timesheet_approve and timeiq_timesheet_submit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It specifies the role restriction 'Manager/Admin only', providing clear usage context. However, it does not explicitly mention when not to use it or suggest alternatives like timeiq_timesheet_approve.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details for a single timesheet by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Only says 'Get details' without mentioning read-only nature, permissions, or whether it modifies state. Minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, straight to the point, no fluff. Front-loaded with verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple get-by-id tool, but 'details' is vague. No output schema, so agent doesn't know what fields to expect. Could list key returned data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter 'id' has no schema description (0% coverage). Description adds 'by ID' clarifying its role as identifier, but does not specify format or origin. Barely adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Get', resource 'timesheet', and scope 'single by ID'. It differentiates from siblings like timeiq_timesheet_list (list all) and action tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this vs alternatives like timeiq_timesheet_list or timeiq_timesheet_by_date. Sibling context suggests explicit comparison would help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List timesheets for the acting user.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not disclose what data is returned, pagination, ordering, or any side effects. For a simple list tool, more transparency about the output format is expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one sentence), but it conveys the core purpose. It could be more concise in wording, but it is not overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and many sibling tools, the description should explain what a timesheet list includes and how it differs from timesheet_by_date or period_list. It lacks this context, making it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so schema coverage is 100%. The baseline is 4, and the description does not need to add parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists timesheets for the acting user. It specifies a verb (list), resource (timesheets), and scope (acting user). However, it does not differentiate from sibling tools like timeiq_timesheet_by_date or timeiq_timesheet_period_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus other timesheet list tools. No exclusions, prerequisites, or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch neighbor timesheets (previous and next) for a target person and timesheet ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| personId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It only states the basic operation without revealing traits like read-only permissions, rate limits, or what happens with edge cases (e.g., missing neighbors).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the core action. However, it is slightly terse and could benefit from additional context without being wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema), the description covers the basic purpose but lacks information about return format, pagination, or edge cases. It is minimally adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It mentions 'target person and timesheet ID' which maps to personId and id, but adds no extra meaning beyond the parameter names (e.g., format, constraints, or context).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb (Fetch) and resource (neighbor timesheets) with contextual details (previous and next, for a target person and timesheet ID). This distinguishes it from siblings like timeiq_timesheet_get or timeiq_timesheet_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor are there any prerequisites or exclusions mentioned. The description implies usage for navigating timesheets but offers no explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the timesheet period covering a specific date.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description does not reveal any behavioral traits such as error handling, response format, or what constitutes a 'timesheet period'. The description fails to compensate for missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no extraneous words. It efficiently states the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and a single parameter, the description lacks essential details: return value, date format, and whether the result is a single period or list. Incomplete for a tool in a larger suite.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no meaning beyond the schema property 'date'. It does not specify format, examples, or constraints, leaving the parameter ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'timesheet period' with the scope 'covering a specific date'. Among siblings, it distinguishes from timeiq_timesheet_period_get and timeiq_timesheet_period_list by focusing on date-based lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives like timeiq_timesheet_period_get. Missing details on valid date formats or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details for a single timesheet period by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations and no output schema, the description should disclose behavioral traits. It only states a read operation but does not mention return format, pagination, error handling, or any constraints. The 'details' are undefined.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no redundant information. It is efficiently front-loaded and direct.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature (1 param, no output schema, no annotations), the description is too minimal. It does not convey what data is returned or how this tool fits among many timesheet-related siblings, leaving ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description adds no meaning beyond 'by ID'. It does not specify what the ID represents, how to obtain it, or any format requirements, leaving the agent to guess.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get details') and the specific resource ('single timesheet period') with the retrieval method ('by ID'). It distinguishes from sibling tools like timeiq_timesheet_period_list (list all) and timeiq_timesheet_period_by_date (get by date).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternative methods (e.g., timesheet_period_by_date, timesheet_period_list). No context about prerequisites or scenarios where this is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all timesheet periods.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states 'list all timesheet periods' without disclosing authentication needs, scope (e.g., user-specific), pagination, or any side effects. The behavioral traits are minimally transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One clear sentence with no wasted words. The purpose is front-loaded and easily understood.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (no parameters, no output schema, no annotations), the description is adequate but lacks contextual details like scope of 'all' (e.g., authenticated user's periods) or return format. It is minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has zero parameters, and the schema coverage is 100% (empty). The description adds no parameter information, but per guidelines, a baseline of 4 is appropriate when there are no parameters to document.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all timesheet periods, which is a specific verb+resource pair. It distinguishes from sibling tools like timeiq_timesheet_period_get (single) and timeiq_timesheet_period_by_date (filtered), though it doesn't explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as timeiq_timesheet_period_get or timeiq_timesheet_period_by_date. The agent has no context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trigger a missing timesheet submission email reminder for a team member.
| Name | Required | Description | Default |
|---|---|---|---|
| personId | Yes | ||
| tsId | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It only says it triggers an email reminder, but omits details on what happens with dry_run, whether it checks if timesheet is missing, or required permissions. The agent lacks essential behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence and is appropriately concise. It front-loads the core purpose. However, it sacrifices necessary detail for brevity, but conciseness is not the main issue.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 3 undocumented parameters, no annotations, and a similar sibling tool, the description is incomplete. It fails to explain parameter usage, outcomes, or when to prefer this over the notification sibling. The agent lacks context to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It provides no information on what personId, tsId, or dry_run represent. The names give hints but do not clarify tsId (timesheet ID or period) or the effect of dry_run. The agent cannot confidently determine how to populate these parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool triggers a missing timesheet submission email reminder. The verb 'Trigger' and the specific resource 'email reminder' provide clear purpose. However, it does not distinguish from the sibling tool timeiq_notification_send_missing_time_reminder, so it loses a point.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like timeiq_notification_send_missing_time_reminder. There is no mention of prerequisites, scenarios, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit a timesheet for review and approval.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| dry_run | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. 'Submit' implies mutation but does not disclose whether it changes state, requires specific permissions, or is reversible. Minimal behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. However, it is overly terse and lacks structure (e.g., separate sections for parameters or return values).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, no annotations, and two undocumented parameters, the description is severely incomplete. It omits return values, side effects, and what 'submit' entails operationally.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description does not explain the required 'id' parameter or the optional 'dry_run' parameter. No guidance on their meaning or usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('Submit') and the resource ('timesheet'), with the purpose 'for review and approval'. It effectively distinguishes from siblings like 'timeiq_timesheet_approve' and 'timeiq_timesheet_decline'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description lacks context such as prerequisites, expected state of the timesheet, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all timesheets flagged with issues (e.g. overbooked, missing required time).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not disclose whether the operation is read-only, has side effects, or requires specific permissions. Listing 'issues' suggests a read operation, but this is not confirmed. The description lacks behavioral context beyond the basic listing action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the essential purpose and examples. No extraneous words. Front-loaded with the main action and resource. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should ideally provide hints about return value structure. It does not mention fields, pagination, or output format. However, for a simple list of flagged timesheets, the description is minimally adequate. Lacks detail for full contextual completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, and the schema coverage is 100%. Per guidelines, 0 parameters earns a baseline of 4. The description adds no parameter info since none exist, which is appropriate. No additional semantics needed beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and resource 'timesheets flagged with issues', with examples (overbooked, missing required time). It effectively distinguishes from other timesheet tools like timeiq_timesheet_list which likely shows all timesheets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for problematic timesheets but does not explicitly state when to use this tool versus alternatives. No 'when not to use' or alternative tool names are given. Usage is inferred from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing time entry with a partial changeset.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| changeset | Yes | ||
| dry_run | No | ||
| requesting_slack_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must fully disclose behavior. It only says 'update with a partial changeset', which implies mutation but does not explain side effects, permissions needed, error behavior, or whether the changeset completely replaces or merges with existing data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise (one sentence) with no fluff. However, it could be slightly more structured with separate clauses for action and parameter hints, but it earns high marks for efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations, no output schema, and 4 parameters including nested objects, the description is insufficient. It omits return value, error conditions, and behavior of optional parameters, leaving the agent under-informed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description adds no parameter details. 'Partial changeset' is vague; the changeset object is unconstrained (additionalProperties: {}), and optional parameters like dry_run and requesting_slack_id are not mentioned.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update), the resource (time entry), and the nature of the update (partial changeset). It effectively distinguishes from sibling tools like timeiq_time_create (create) and timeiq_time_delete (delete), and subtly differentiates from timeiq_time_update_many by implying singular update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like timeiq_time_update_many for bulk updates, or prerequisites such as requiring an existing time entry ID. The description lacks any contextual usage hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update multiple time entries with the same changeset. Safe-guarded for actions exceeding 50 entries.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | ||
| changeset | Yes | ||
| confirm_bulk | No | ||
| dry_run | No | ||
| requesting_slack_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present. The description adds minimal behavioral context beyond a vague 'safe-guarded' note. It fails to explain what the safeguard entails, whether confirm_bulk or dry_run affect behavior, or what the return value looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at one sentence, but it omits critical parameter details, making it insufficiently informative. It earns a middle score because it is not verbose, but the lack of detail reduces usefulness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters, 0% schema coverage, no annotations, and no output schema, the description is starkly incomplete. It does not address parameter semantics, return values, prerequisites, or edge cases like the 50-entry limit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description does not explain any parameter. The meaning of 'ids', 'changeset', 'confirm_bulk', 'dry_run', and 'requesting_slack_id' is left entirely to inference, providing no added value over the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update multiple time entries) and mentions applying a single changeset. However, it does not differentiate from sibling tools like timeiq_time_update or timeiq_time_batch, missing an opportunity to clarify scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes a safeguard for actions exceeding 50 entries, implying a boundary condition, but provides no guidance on when to use this batch update versus alternatives or prerequisites such as required parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the site URL for the tenant domain.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description implies a read-only operation but does not explicitly state side effects or safety. Lacks detail on authentication or rate limits, but basic transparency is sufficient for a simple getter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no unnecessary words. Efficient and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Minimal context: does not explain what the site URL is for or what the output looks like. Adequate given simplicity, but could mention that it returns the tenant domain's base URL.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters in schema, description coverage 100%. Nothing to add beyond schema, baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get the site URL', specifying verb and resource. It distinguishes from sibling tools which cover billing, expenses, clients, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus others, no prerequisites or context provided. Single sentence lacks usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the profile and settings of the currently authenticated acting user.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'Get', implying read-only operation with no side effects. However, it does not specify whether any authentication is required beyond being authenticated, nor does it detail the response structure. For a simple read tool, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that directly states the tool's purpose without any unnecessary words or repetition. It is well structured and front-loaded with the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description should ideally explain what 'profile and settings' includes (e.g., name, email, preferences). While it provides a general idea, it lacks specificity about the return value or any possible error conditions. It covers the basics but is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description correctly has no parameter info. Per the guidelines, 0 parameters gives a baseline of 4. The description adds value by explaining what the tool returns (profile and settings), which compensates for the lack of parameter detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Get' and the resource 'profile and settings of the currently authenticated acting user'. It distinguishes this tool from siblings by focusing on the current user's identity, as opposed to creating or managing other entities like clients, invoices, or projects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives, but the context is implied: it is the tool to retrieve own profile info. Since it has no parameters and a straightforward purpose, the usage is clear enough, but explicit guidance on when not to use it (e.g., when needing another user's profile) is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have clear resource+action patterns, making them distinguishable. However, the large number of report tools (e.g., timeiq_report_classic, timeiq_report_custom, timeiq_report_expenses, etc.) are similar in purpose and could cause confusion, reducing the score from perfect.
All tools follow a consistent 'timeiq_<resource>_<action>' naming pattern, with clear noun-verb structure. Even variations like timeiq_timer_start are consistent within their resource group. No mixing of conventions.
With 126 tools, the server is far too large for typical MCP usage. This overwhelms the agent with choices and likely violates best practices. The number is excessive for any single server.
The tool set comprehensively covers the domain of time tracking, invoicing, expense management, projects, clients, and reporting. All expected CRUD operations and workflows are present, with no obvious gaps.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
MCP server exposing klokin time-tracking operations (employees, time entries, stores) to AI clients.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Hosted MCP server for Cliniko — patients, appointments, availability, and invoices for AI agents.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Tomi2k/timeiq-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
