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

With no annotations present, the description carries the full burden and delivers: cascade deletion of attachments, a 14-day recoverability window versus permanent purge afterward, and a distinct blocks:delete scope separate from blocks:write that must be granted deliberately. It also pre-empts an incorrect user-facing claim about irreversibility.

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

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

Long but denser than it looks: every sentence is a distinct guardrail (target identification, user confirmation, no batching, reversibility window, scope requirement). The destructive action is front-loaded and no sentence is 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 an irreversible-leaning destructive tool with no annotations and no output schema, this covers everything an agent needs: exactly what is destroyed, how to confirm, how to recover, what scope is required, and what to tell the user afterward.

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

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

Schema coverage is 100% and the single parameter already documents that the id comes from list_time_blocks. The description only reinforces cardinality ('Exactly one block is deleted'), adding little beyond the schema. Baseline 3 applies.

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

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

States a precise verb and resource ('Permanently delete ONE recorded time block') and immediately scopes the side effect ('along with any files attached to it'). The 'ONE' emphasis cleanly separates it from ranged or bulk operations and from siblings like list_deleted_time_blocks and restore_time_block.

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

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

Gives explicit preconditions (must show the user the specific block pulled from list_time_blocks and get an explicit yes), explicit prohibitions (never infer from a vague instruction, never delete a range at once), and names the alternative path (restore_time_block within 14 days). Nothing is left 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses ordering (newest first), the per-item payload (deletion date, restore deadline), and the required blocks:read scope — solid context. It stops short of return-shape details like pagination or whether expired blocks drop off.

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

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

Three sentences, front-loaded with what the tool returns before the usage instruction and the scope requirement. No filler; each sentence carries distinct information.

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

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

With no output schema and no annotations, the description must explain the return payload and auth needs — it does both (item contents, ordering, blocks:read scope). Pagination and result limits are the only meaningful omissions for a list endpoint.

Complex tools with many parameters or behaviors need more documentation. 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, so the baseline is 4. There is no parameter surface for the description to clarify, and it correctly doesn't waste words on nonexistent inputs.

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

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

States a specific resource and qualifier: time blocks that were deleted but are still restorable. This clearly distinguishes it from the sibling list_time_blocks, which covers active blocks, so an agent can pick correctly without opening the schema.

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

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

Explicitly routes usage: 'Use it to find the block_id for restore_time_block when the user says they deleted something by mistake.' It names the sibling tool it feeds and the triggering user condition, leaving nothing 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?

With no annotations, the description carries the full burden, and it delivers the key operational facts: visibility scope ('every project the account can see'), the required projects:read scope, and the read-only nature implied by 'List'. It omits pagination/result-size behavior for what could be a large collection.

Agents need to know what a tool does to the 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 what is returned, then why to call it, then the auth prerequisite. No filler or 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?

No output schema exists, so the description compensates by naming the returned fields, and it also discloses the required scope. The only material gap is the absence of any pagination or volume guidance for a potentially unbounded list.

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

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

Zero parameters, so the baseline is 4. The description usefully clarifies that the output id is the project_id consumed by other tools, adding context beyond the empty 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?

States a specific verb+resource ('List every project the account can see') and enumerates the returned fields (id, name, colour, role). This is unmistakably distinct from siblings such as list_tasks and list_time_blocks, which target entirely 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?

Explicitly states when to use it: to resolve a user-typed project name into the project_id that other tools require. That is a strong, concrete usage context, though it names no exclusion or explicit alternative tool for listing projects.

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?

No annotations are provided, so the description carries the behavioral burden, and it does disclose the required 'projects:read' scope, which is a non-obvious auth prerequisite. 'List' implies read-only, but pagination, result caps, and whether subtasks are nested or flattened are not addressed.

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

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

Three short sentences, front-loaded with what is listed and returned, followed by filtering and the use case. No filler and every sentence contributes information.

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

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

With no output schema, the description usefully enumerates returned fields, the filtering mechanism, the downstream consumer (log_time), and the auth scope. It leaves pagination/result-size behavior and subtask nesting unstated, a minor gap for a simple two-parameter list tool.

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

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

Schema description coverage is 100%, so both parameters are already documented, setting the baseline at 3. The description reinforces project_id as the project filter but never mentions active_on, adding little semantic 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?

States a specific verb and resource ('List Gantt tasks (and subtasks)') and enumerates the returned fields (id, project, name, date range), so an agent knows exactly what comes back. It is distinguishable from siblings like list_projects and list_time_blocks by its task-level scope and inclusion of subtasks.

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

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

Gives a concrete primary use case: 'resolve a task name into the task_id that log_time takes,' which names the consuming sibling. It also tells the agent how to narrow results with project_id. It stops short of stating when NOT to use it (e.g., versus list_projects for enumerating projects), so not a full 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?

With no annotations, the description carries the burden and does well: it discloses the inclusive date semantics, a max 92-day range limit, and the required blocks:read scope. It omits ordering/pagination behavior and result-size expectations, which keeps it from a 5.

Agents need to know what a tool does to the 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 tight sentences with no filler; the scope constraint precedes the alternative-tool routing. It opens as a noun phrase rather than a verb, which slightly weakens the front-loading of the action, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 two-parameter read tool with no output schema, the description supplies the return fields, the permission requirement, and the range cap — enough to call it correctly. Only ordering/pagination details are missing, which is minor.

Complex tools with many parameters or behaviors need more documentation. 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 both date parameters are already documented as YYYY-MM-DD inclusive. The description adds a real constraint not present in the schema — the 92-day maximum span — which meaningfully constrains how the agent should call 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?

Names the specific resource (individual time blocks), the scope (logged between two dates), and the returned fields (start/end, duration, project, task, memo). It explicitly differentiates itself from the sibling time_summary, so an agent can pick correctly without opening a schema.

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

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

Gives a clear routing rule: 'use time_summary when you only need totals,' which tells the agent when the alternative is preferable. It stops short of stating exclusions (e.g., what to use for deleted or unfiltered blocks), so it is strong but not fully prescriptive.

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 full burden and does well: it discloses that this mutates the user's real schedule, requires the blocks:write scope, and needs PYUNTO_TM_PASSWORD for encrypted memos. It omits other behavioral traits such as overlap/conflict handling, reversibility, or validation errors.

Agents need to know what a tool does to the 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 tight sentences with the mutation side-effect and the confirm-first warning front-loaded. No filler, though the sentence packing scope, memo and password into one clause is slightly dense.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 6-param mutation tool with no annotations and no output schema, the description covers side effects, auth and the encryption password requirement well. It leaves gaps around conflict/overlap behavior and what a successful call returns, but is otherwise adequate.

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

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

Schema description coverage is 100%, so every parameter is already documented, giving a baseline of 3. The description adds only marginal parameter meaning beyond the schema (the memo/encryption context), which the schema already states as 'Encrypted client-side'.

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

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

States a specific verb+resource ('Record a block of worked time on the calendar'), so the agent knows exactly what it does and can tell it apart from read tools like list_time_blocks. It does not explicitly contrast with update_time_block or delete_time_block, which would have sharpened sibling differentiation.

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

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

Gives a clear usage condition and a prerequisite: confirm project, date and times with the user before calling, since it writes to the real schedule. It stops short of naming the alternative tools (e.g. update_time_block) or stating when not to use this one.

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 full burden and does well: it discloses the permission requirement (blocks:write scope), the irreversibility after 14 days, and the side effect of reattaching files. It stops short of saying how failures present (e.g., block already restored or window expired), which is the one behavioral 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?

Three short sentences, action first, then sourcing guidance, then the constraint and permission. No redundant or filler content.

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

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

For a one-parameter mutation with no annotations and no output schema, the description covers purpose, input source, permission, and the recovery-window limit. It omits error/response behavior, but everything needed to invoke it correctly is present.

Complex tools with many parameters or behaviors need more documentation. 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 single parameter's description already points to list_deleted_time_blocks, so the description adds no syntax or format detail beyond what the schema states. Baseline 3 is correct for a one-param tool with full schema coverage.

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

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

Specific verb ('Put ... back') plus resource ('a deleted time block') with the attached-file side effect called out, which cleanly distinguishes it from delete_time_block and update_time_block. An agent can pick this over its siblings without reading any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 names the companion tool that produces the required input (list_deleted_time_blocks) and states the hard usage boundary (14-day recovery window, after which the block is unrecoverable). No explicit 'when not to use this vs. another restore path' exists, but the prerequisites are clear.

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 and does so well: it discloses the 92-day maximum range, that dates are inclusive, the available grouping modes, and the required record:read permission. What it does not cover is output shape or how totals are formatted, leaving a small gap for a no-annotation tool.

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

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

Two tight sentences: the capability and its bounds come first, then the use case. No filler and no repetition of the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 three-parameter aggregation tool with no output schema, the description covers scope, grouping, limits, and auth requirements so an agent can call it correctly. The only omission is any hint about the shape of the returned totals, which is minor given the group_by field.

Complex tools with many parameters or behaviors need more documentation. 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, and the description adds a real constraint the schema omits: the 92-day maximum span between date_from and date_to. It also restates the grouping vocabulary, which the schema already enumerates, so value beyond baseline is moderate rather than rich.

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

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

States a specific operation (totaling hours logged) over an explicit resource (time records) with a bounded date window and three named groupings. It is clearly distinguishable from siblings like list_time_blocks, which return raw entries rather than aggregated totals.

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

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

Gives concrete use cases ('how much time did I spend on X', writing a work log or diary entry), which tells the agent when this tool is the right pick. It does not explicitly name or exclude the alternative listing tools, so it stops short of full when-not guidance.

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 full burden and does well: it discloses partial-update semantics ('Only the fields you pass change'), the required blocks:write scope, and the special PYUNTO_TM_PASSWORD + project_id requirement for encrypting memos on end-to-end-encrypted projects. It omits reversibility and result behavior, but the authorization and mutation semantics are unusually well covered.

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

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

Four tight sentences, front-loaded with the mutation scope before the prerequisites. Every sentence carries operational weight, though the memo/encryption sentence is dense enough that it could be split for readability.

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

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

For a 7-parameter mutation tool with no annotations and no output schema, the description covers identity lookup, partial-update behavior, scope, and the encryption prerequisite. Return-value details are absent but the tool has no output schema, and reversibility guidance is the only notable omission.

Complex tools with many parameters or behaviors need more documentation. 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 already 100% (baseline 3), and the description adds meaning beyond it by explaining where block_id comes from and why project_id must accompany a memo (so the memo is encrypted under the right key). That cross-parameter dependency is genuine 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?

States a specific verb ('Change') and resource ('an already-recorded time block') and enumerates exactly which fields are mutable (date, start/end, memo, task attribution). This clearly distinguishes it from siblings like log_time (create), delete_time_block, and list_time_blocks without needing to name 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?

Gives concrete context: obtain block_id from list_time_blocks, and confirm the current vs. intended state with the user before calling. It stops short of stating when not to use this tool (e.g., versus log_time for new entries), so it is strong but not exhaustive.

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?

No annotations are provided, so the description carries the burden, and it does meaningfully: it discloses the exact contents returned (email, key name, scopes, server URL, E2E decryption status) and frames the tool as a read-only diagnostic. It does not explicitly state that it is side-effect free, but the identity-inspection framing makes that clear.

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

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

Two sentences: the first front-loads what is returned, the second front-loads the diagnostic trigger. No filler, no restatement of the tool name.

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

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

There is no output schema and no annotations, so the description must explain what comes back — it enumerates the returned fields — and it supplies the diagnostic use case. Nothing an agent needs in order to decide to call this zero-parameter tool is missing.

Complex tools with many parameters or behaviors need more documentation. 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, so per the rubric the baseline is 4. The description correctly adds no parameter detail because there is nothing to parameterize, and the 100% schema coverage leaves no gap to compensate for.

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

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

States a specific verb+resource — it returns the identity this MCP server is connected as — and enumerates the exact fields (account email, API key name, scopes, server URL, encryption capability). This is clearly distinguishable from every sibling, which is a time-tracking domain 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?

Gives an explicit trigger: "Call this first when a tool fails, to see which scopes are missing." That is a concrete when-to-use condition. It does not name any competing tool or an exclusion, but no sibling overlaps this diagnostic role, so ambiguity is low.

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