Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations mark the tool as destructive and not read-only, but the description adds crucial specifics: it discards unbooked time, does NOT save a time entry, and requires user confirmation. This goes well beyond what annotations already convey and clearly warns about data loss.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences front-load the destructive action and its most important consequence, then provide the alternative and confirmation requirement. There is no filler or redundant explanation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 two-parameter tool, the description covers what happens, what does not happen, the need for confirmation, and how to preserve tracked time. It loses a point because the alternative tool name is inaccurate relative to the sibling list, which weakens otherwise complete 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?

The schema already documents both parameters fully, so the baseline is 3. The description adds an important workflow detail — 'Ask the user to confirm' — and reinforces that 'confirm' is a destructive-confirmation flag, adding useful semantic context 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 a specific action ('STOPS the running clock') and its consequence ('DISCARDS the unbooked time'), and explicitly distinguishes itself from saving or keeping an entry. This prevents confusion with the sibling clockodo_delete_entry and makes the tool's scope unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly tells the agent when not to use this tool ('To keep tracked time, use ... instead') and instructs to ask the user for confirmation. However, it names 'clockodo_update' as the alternative, while the sibling list contains 'clockodo_update_entry' — an inaccurate reference that could mislead tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide no behavioral hints, so the description carries the burden. It discloses the one-clock constraint and that time is counted live until stopped, which are the critical behavioral facts. It does not describe what happens if a clock is already running or what response the agent should expect, leaving a moderate 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 three short sentences with no filler: action first, then required/optional parameters, then the critical one-clock caveat. Every sentence contributes directly to correct invocation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, stateful tool with no output schema, the description covers the core operational constraints and inputs needed to use it safely. It stops short of explaining the failure behavior when a clock is already running or which tool should be used to stop it, but an agent has enough context to check status and proceed.

Complex tools with many parameters or behaviors need more documentation. 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 lists required versus optional parameters without explaining what customers_id, services_id, or projects_id semantically represent. It does enumerate all five parameters, which is marginally helpful, but it does not compensate for the complete absence 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 opens with a specific action and resource: 'Starts the running clock (live tracking).' It clearly frames this as the live-tracking tool and distinguishes it from manual entry creation or clock deletion by emphasizing the running-clock state. The required parameters reinforce exactly what is needed to invoke 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?

It explicitly says 'Only one clock can run at a time — check clockodo_clock_status first,' which gives a clear precondition and points directly to the relevant sibling tool. This tells the agent when to call this tool and when to pause: after checking clock status. That is strong usage guidance for a stateful action.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The readOnlyHint annotation already covers the read-only safety profile. The description adds useful context that the running entry is 'started but not yet saved' and has type 'clock', but it does not describe response shape, empty-state behavior, or other constraints. Acceptable, but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no filler. The core fact — running, unsaved, type 'clock' — is front-loaded and every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only status tool, the description adequately identifies what is returned and that it may be absent ('if any'). Explicit return-shape or null-handling details would strengthen it, but the tool can be called correctly based on the information 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?

The tool has zero parameters and an empty input schema, so there is no parameter meaning for the description to add. The baseline for 0 parameters applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Returns') and resource ('currently running clocked time') and clarifies it is the unsaved running entry with type 'clock'. It is clear, though it does not explicitly name or contrast sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool — to check the currently running clock — but provides no explicit guidance about alternatives such as clockodo_clock_start, clockodo_clock_delete, or list_entries. Sibling differentiation is left mostly to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide only basic flags, so the description carries the burden of explaining behavior. It does so well by disclosing required fields, the two mutually exclusive time formats, optional text use, and the admin-only constraint on users_id. It doesn't describe response behavior, but for a create operation the core side effect and constraints are clear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and information-dense. Every sentence earns its place: the main action, required parameters, time alternatives, and optional fields with their constraints. No filler or repetition exists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 9-parameter create tool with no output schema, the description covers the essential call-building information: required IDs, billable flag, the two valid time combinations, and optional parameters. It is complete enough for a correct first call, though it doesn't describe the response format or 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 description coverage is only 56%, so the description must compensate. It adds meaningful semantics beyond the schema: which parameters are required, that time_since is always required with either time_until or duration, that duration is in minutes, that users_id is admin-only, and that text should be sourced from clockodo_list_entry_texts. This goes well beyond bare schema 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 opens with 'Creates a time entry', which names a specific verb and resource. This clearly distinguishes the tool from siblings like update, delete, get, and list operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly frames when this tool is appropriate: to create a time entry, with required parameters and time-option alternatives. It also explicitly points to clockodo_list_entry_texts as the recommended source for text naming, providing useful cross-tool guidance, though it does not explicitly describe 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Even with annotations declaring destructiveHint and idempotentHint, the description goes beyond them by explaining the real behavioral effect: the entry is not hard-deleted but remains in reports flagged 'deactivated'. It also adds the operational requirement of user confirmation. This provides genuinely useful behavioral context that annotations alone do not convey, with no contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences carry all essential information: the behavioral distinction, the no-hard-delete consequence, and the confirmation prerequisite. The most important word 'DEACTIVATES' is front-loaded, and every sentence earns its place with zero filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no output schema, the description covers what action is taken, what the side effect is (stays in reports), and the required confirmation. It does not explicitly discuss return values or failure modes, but those are not needed given the schema and annotations. It is complete enough for an agent to call correctly in most realistic scenarios.

Complex tools with many parameters or behaviors need more documentation. 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 only 50% — the 'confirm' parameter is well-described in the schema, but 'id' has no description. The tool description indirectly clarifies that 'id' refers to a time entry, and it reinforces the confirm requirement, but it does not add substantial new meaning beyond the schema. Given the low coverage, it partially compensates but does not fully bridge the 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 a specific action ('DEACTIVATES a time entry') on a specific resource, and immediately distinguishes the tool from a hard delete by explaining Clockodo has no hard delete. This makes it unmistakable what the tool does and how it differs from siblings like clockodo_create_entry or clockodo_clock_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 provides clear usage context: it tells the agent to ask the user for confirmation before calling and emphasizes the 'confirm' parameter. It does not explicitly compare to alternatives (e.g., using clockodo_update_entry to set a status), but its role as the deactivation/soft-delete mechanism is implied strongly enough for an agent to select it appropriately. Missing explicit exclusions prevents a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, so the description's job is lighter. It adds value by mentioning the deactivated flag, but it does not disclose behavior on missing ids, error responses, or whether soft-deleted entries are included. This is acceptable but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One compact sentence carries the core purpose plus a relevant return detail. There is no filler, and the key scoping information ('single time entry by id') is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read-only fetch tool, the description covers the essential purpose and the notable return flag. No output schema exists, but the lack of detailed return documentation is less critical for such a simple get operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the only parameter, id, is already described as 'entry id'. The description confirms id is the selection key but adds no additional format, constraints, or 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 states a specific verb ('Fetches'), a specific resource ('a single time entry'), and a distinguishing detail (includes 'its deactivated flag'). It clearly differentiates from sibling list tools like clockodo_list_entries, which fetch 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 makes the tool's use case clear: fetch one specific time entry by id. It does not explicitly name an alternative or exclusion condition, but the sibling set makes it evident that list_entries is for broader queries and create/update/delete are for mutations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The readOnlyHint annotation already declares the operation safe, lowering the bar. The description mentions 'Optional: page' which hints at pagination but does not explain behavior like result ordering, response shape, or any side effects. No extra behavioral context is added beyond what the annotation provides.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and front-loaded with the core purpose. The second sentence about optional parameters is somewhat redundant with the schema but adds a quick summary. No fluff, and the structure 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?

For a simple list tool with no required parameters and a read-only annotation, the description is mostly adequate. It lacks details on pagination behavior or output structure, but these are less critical given the tool's simplicity. The missing page semantics are 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?

Schema description coverage is 50%, with 'page' lacking any schema description. The description's 'Optional: page, name filter' adds no real meaning beyond restating optionality and name filtering, which is already partly in the schema. It does not clarify what 'page' represents or how it affects results, leaving a gap that the description should have filled.

Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 a specific verb and resource: 'Lists customers.' This clearly distinguishes it from sibling list tools like list_projects and list_users, each targeting a different entity. The purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the resource name: an agent would use this when needing to list customers. However, the description provides no explicit context, no when-not-to-use guidance, and no alternatives. There is no mention of conditions that would favor a different tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With readOnlyHint=true already signaling a safe read, the description adds valuable behavior: the response contains paging and further pages should be requested only on user request. This goes beyond the annotation without contradicting it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the action and then compressing the parameter details. Every sentence contributes distinct information with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a moderately complex list tool with no output schema, the description covers required inputs, optional filters, and pagination behavior. It does not detail the entry fields in the response, but the absence is minor given the descriptive tool name and read-only annotation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds the ISO format example and the 50-per-page page size, which are not in the schema. It also groups parameters into required vs optional.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear verb-resource pair: 'Lists time entries in a time range.' It names the core scope and optional filters, making it easily distinguishable from sibling tools by content, though it does not explicitly reference 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?

It supplies required and optional parameters and instructs the agent to fetch further pages only if the user asks. However, it does not state when to prefer this over clockodo_get_entry or other list tools, so usage guidance is implied rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The readOnlyHint annotation already declares this is a safe read operation, and the description does not contradict it. The description adds useful context beyond the annotation by explaining these are 'recurring descriptions' intended for consistent naming when creating entries, which clarifies the nature of the data returned. It does not detail pagination or other behaviors, but for a simple read-only list, this is sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loading the core function in the first sentence and the usage intent in the second. Every word earns its place, with no fluff, filler, or redundant details. It is a model of conciseness for a simple lookup 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?

For a simple read-only list tool, the description covers the purpose and usage well. However, it omits any mention of pagination, despite the 'page' parameter existing in the schema. Since the tool lists predefined texts, there could be many results, and an agent should know whether results are paginated or how to get all of them. This missing detail is a notable gap, though not fatal given the otherwise clear intent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema documents 'term' with 'search substring' (50% coverage), but 'page' has no schema description. The tool description does not mention either parameter, let alone compensate for the undocumented 'page'. With schema coverage at only 50%, the description should at least hint at pagination or that 'page' controls paging, but it is completely silent, leaving the agent to guess the meaning of a common pagination 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 explicitly states the verb 'Lists' and the resource 'account's predefined entry texts (recurring descriptions)', making the tool's purpose unmistakable. It also ties the purpose to a concrete action ('Pass one as text when creating entries'), which clearly differentiates it from sibling tools like clockodo_list_entries (which lists time entries) and clockodo_create_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?

The description gives explicit guidance on when to use the tool: when needing a text to pass when creating entries for consistent naming. It does not name alternative tools or explicitly state when not to use it, but the context of 'predefined entry texts' is sufficient to infer its role relative to siblings. A clearer exclusion (e.g., 'for time entries, use clockodo_list_entries') would push this to a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds the available filter dimensions but discloses no other behavior such as pagination behavior, default page size, or ordering. This is adequate for a read-only list tool 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?

One short sentence front-loads the core action and then lists filters without wasted words. All content is relevant and efficiently structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only list endpoint with four optional filters, the description covers the key selection dimensions. However, with no output schema, it does not disclose response shape or pagination semantics, and 'page' is left to inference. This is mostly complete but has minor gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema descriptions already cover name, active, and customers_id (75% coverage); the description mostly restates them as 'filter' or 'active-only'. The 'page' parameter remains undocumented in both schema and description, though its purpose is self-evident. The description adds no format, defaults, or edge-case 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 uses a specific verb and resource ('Lists projects') and the optional filters clarify scope. It is distinct from sibling list tools like clockodo_list_customers or clockodo_list_users, which target different resources. No ambiguity exists about what the tool returns.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 or when to prefer an alternative, and no exclusion criteria are given. The optional-filter phrasing implies usage for retrieving projects with optional narrowing, but guidance is only implied rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful context about scope ('all users') and return fields, but it does not clarify pagination behavior even though the schema exposes a 'page' parameter. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence that is efficient, front-loaded, and contains no filler. It communicates the core action, target resource, and key return fields 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?

The tool is simple, but the undocumented 'page' parameter is a real gap. The phrase 'all users' is ambiguous when a pagination parameter exists, and the lack of an output schema means the description should clarify expected results beyond 'ids and roles'. The definition is too thin to be fully reliable 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 only parameter, 'page', has no schema description and schema description coverage is 0%. The description also does not mention the parameter at all, so the agent receives no semantic information about how pagination works or what 'page' means.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses a specific verb ('Lists'), identifies the resource ('all users (team members)'), and states the returned fields ('ids and roles'). It is easily distinguishable from sibling tools like clockodo_list_entries or clockodo_list_customers, which target different resources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when you need all users and their roles, but it does not explicitly mention alternatives or when not to use this tool. Among the siblings, clockodo_me is the closest alternative for user info, but no routing guidance is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of disclosing behavior. 'Returns...' signals a read-only operation, and the phrase 'verify the connection' implies the success/failure behavior an agent can rely on. It does not discuss errors or auth details, but those are not critical for a zero-parameter read endpoint.

Agents need to know what a tool does to the 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 front-loads the most important information (what is returned), adds concrete fields, and then gives a short usage directive. 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 read-only endpoint with no output schema, the description fully covers what an agent needs: what the call returns and that it should be used first to verify connectivity.

Complex tools with many parameters or behaviors need more documentation. 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 takes zero parameters and the schema is empty, so there is nothing for the description to clarify. Per baseline for zero-parameter tools, a 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?

The description uses a specific verb ('Returns') and a specific resource ('the authenticated Clockodo user') and enumerates the fields it contains, making the tool's purpose immediately clear. It is clearly distinct from sibling tools like clockodo_list_users, which list all users, by emphasizing the authenticated user.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit usage context: 'Use this first to verify the connection.' It does not name alternatives or when-not-to-use cases, but for a simple self-metadata endpoint the guidance is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already convey non-readonly and non-destructive behavior. The description adds valuable behavioral context by clarifying partial-update semantics and the customers_id/projects_id consistency rule, which is not inferable from the schema alone.

Agents need to know what a tool does to the 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 filler. The core update semantics and the critical domain constraint are presented directly and 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 covers partial-update semantics and a key invariant, which is good. However, with 9 parameters, sparse schema coverage, and no output schema, an agent still lacks critical formatting and return-value context to confidently invoke the tool in all cases.

Complex tools with many parameters or behaviors need more documentation. 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 only 11% (only duration is documented). The description adds almost no parameter-level meaning beyond the customers_id/projects_id relationship, leaving most parameters such as time_since, time_until, services_id, and text 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 'Updates an existing time entry,' which is a specific verb + resource. It is immediately distinguishable from sibling tools like create_entry, get_entry, and delete_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?

It explicitly instructs callers to pass only the fields to change and at least one field, which defines the intended invocation pattern. It does not name alternatives or state when not to use the tool, but the partial-update guidance is clear and useful.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.