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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds minimal behavioral detail beyond the core purpose; it does not describe ordering, default limits, or result shape, but nothing contradicts the annotations.

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

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

Two sentences, front-loaded with the core action, and no filler. Every sentence 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?

The description plus schema is sufficient for an agent to select and call the tool correctly in most cases. The only notable gap is the absence of an output schema and no description of what each log entry contains, but the core invocation details are covered.

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 high at 83%, so the schema carries most parameter documentation. The description's mention of 'since the last session' gives a useful real-world interpretation of the `since` parameter, but it does not add meaning for the other 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 ('View') and the resource ('the activity log') and adds what the log shows: 'what changed and when.' It does not explicitly differentiate from nearby siblings like tracker_session_diff or tracker_dashboard, so it falls just short of a 5.

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 concrete usage context: 'understanding recent progress or reviewing what happened since the last session.' This implies when to use it, but it does not mention when not to use it or point to alternatives.

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 indicate this is a write operation (readOnlyHint=false). The description adds context about chronological threading but does not disclose potential side effects like updating task metadata. 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?

Two sentences, front-loaded with the action, no fluff. Every sentence 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?

For a simple write tool with 3 parameters and no output schema, the description adequately covers purpose and use case. Could mention the return value or note that comments append to existing thread, but not essential.

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% with clear parameter descriptions. The tool description does not add additional meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the action 'Add a comment to a task' and elaborates on its purpose as creating a chronological discussion thread for cross-session context. It distinguishes from sibling tools like comment_list and task_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 for leaving breadcrumbs across sessions but does not explicitly state when to use this tool versus alternatives like note_save or task_update. No direct guidance on exclusion criteria.

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?

Goes well beyond the annotations by revealing that the row is retained for the audit trail, is hidden from listing/reading operations, and can be restored. This is exactly the kind of non-obvious behavioral context that annotations alone do not capture.

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 with no wasted words. The core behavior is front-loaded, followed by the key consequence and the recovery path. 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?

Given the simple 3-parameter, no-output-schema tool, the description covers the operation's effect, visibility changes, audit implications, and reversibility. Nothing essential is missing for an agent to invoke 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?

The schema already documents all three parameters at 100% coverage, so the baseline is 3. The description adds meaningful context for the 'reason' parameter by noting it stays in the audit trail, which deepens the agent's understanding of what to supply and why.

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 a specific verb ('Remove'), a specific resource ('a comment'), and clarifies that this is a soft delete with concrete visibility consequences (hidden from comment_list and task_get). It clearly distinguishes this from comment_add and comment_restore even without exploring schemas.

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 says to use this to retract a comment that is wrong or stale, and names the recovery alternative ('Reversible with comment_restore'). This gives the agent clear selection criteria between the delete and restore operations.

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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds non-obvious behavioral detail beyond those annotations: results are chronological, soft-deleted comments are hidden by default, and passing include_deleted reveals them along with their removal reason. This materially improves the agent's understanding without contradicting 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?

Two sentences with no filler. The first sentence states the action, resource, and ordering; the second explains the conditional flag. Every clause earns its place and the most important information is front-loaded.

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

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

For a read-only list tool with two simple parameters, strong annotations, and no output schema, the description is complete. It covers what is listed, the ordering, the default filtering behavior, and the purpose of the optional parameter. There are no critical gaps that would prevent 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 is 100%, so the baseline is 3. The description adds value beyond the schema by explaining that include_deleted surfaces removed comments 'with their removal reason' and by clarifying the chronological ordering, which gives the agent a better sense of what the output will be. This goes slightly beyond the schema's own parameter 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 uses a specific verb ('List') and resource ('comments on a task'), and adds 'chronological order' to define the scope and output semantics. It is immediately distinguishable from sibling comment tools like comment_add, comment_delete, and comment_restore by its read-oriented action and the explicit reference to comment_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 clearly establishes the core use case: retrieving comments for a task. It also gives concrete guidance on the include_deleted parameter, explicitly stating that removed comments are hidden by default and explaining when to set the flag. This is sufficient guidance given that no alternative comment-listing sibling exists.

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 provide the key behavioral traits: readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds the useful precondition that the comment must have been removed with comment_delete, which is context beyond the annotations. However, it does not disclose outcomes such as whether the restored comment returns to its original position or any error behavior.

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

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

The description is a single clear sentence with no filler. The action and precondition are front-loaded, making it immediately scannable for an 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?

For a simple one-parameter mutation with rich annotations and full schema coverage, the description is nearly complete. It could improve slightly by stating what happens after a successful restore or what the response is, but the current combination of schema, annotations, and description is sufficient 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?

Schema description coverage is 100%, and the schema already states 'Comment ID to restore.' The tool description adds no additional meaning about the parameter beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description states a specific action ('Restore') and resource ('comment'), and clarifies it applies to comments previously removed with comment_delete. This distinguishes it from comment_delete, comment_add, and comment_list without needing to open 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?

The description clearly indicates the intended use case: undoing a prior comment_delete. It references the relevant sibling tool and context. It does not explicitly list when not to use the tool, but the precondition is specific enough for an agent to route correctly.

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?

Beyond the annotations, the description discloses important behavioral effects: archived epics and their tasks drop out of listings, the dashboard, and search unless include_archived is set. It also confirms that no data is deleted, which complements the idempotentHint and destructiveHint annotations without contradicting them.

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

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

The description is compact and efficiently ordered: the core action comes first, followed by the observable side effects and the intended use case. Every sentence earns its place, and there is 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 two-parameter tool with annotations covering idempotence and non-destructiveness, the description is nearly complete: it explains the action, the side effects on visibility, and the non-destructive nature. It does not describe expected return values or permissions, but with no output schema and a simple interface, this is not a significant 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 documents the archived parameter clearly ('true to archive, false to bring it back'), and the description reinforces this with 'archive or unarchive.' However, the required id parameter has no schema description and the tool description does not explicitly explain that id refers to the epic identifier, leaving a minor gap at 50% 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?

The description uses a specific verb and resource pair, 'archive or unarchive an epic,' and clearly explains the state change. It also distinguishes the operation from deletion by stating 'nothing is deleted,' which removes ambiguity about what the tool does.

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 a clear use case: putting finished work out of sight without cancelling it, which implies it should be used instead of destructive deletion or a regular update. It does not explicitly name sibling alternatives or state when not to use it, but the context is strong enough for an agent to make the right call.

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 cover read-only, destructive, and idempotency hints. The description adds the domain behavior of grouping tasks but does not disclose extra operational details such as whether the project must already exist, how duplicates are handled, or what happens after creation. It does not contradict the annotations.

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

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

The description is two sentences and directly states the action and conceptual purpose without fluff. It is well front-loaded, though the second sentence could have provided operational guidance instead of repeating the obvious epic concept.

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 seven parameters and no output schema, and the description only covers the high-level purpose. Required parameters can be inferred, and the schema handles enums and defaults, but the description does not mention the expected return value, prerequisites, or behavior of optional fields. It is 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?

Schema description coverage is 57%, and the description adds essentially no parameter-level meaning. It loosely relates 'project' to project_id and 'related tasks' to the epic's purpose, but it does not clarify tags, status, priority, or branch behavior beyond what the schema already provides. The description does not compensate for the undocumented 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 uses a specific verb and resource: 'Create an epic within a project.' It also explains the concept of an epic by stating that epics group related tasks into a feature or workstream, which distinguishes it from sibling tools like epic_list, epic_update, and epic_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 gives clear context for when to use the tool: when creating an epic in a project to group related tasks. It does not explicitly mention alternatives or exclusions, but this is a creation tool and the intended use is straightforward.

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 establish readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds behavioral context beyond the annotations by disclosing that archived epics are hidden by default unless include_archived is set, and that task counts and completion stats are included in the response.

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 first states the core action and return value, the second covers filtering and archived behavior. Every sentence earns its place with no filler or repetition of schema 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?

For a read-only listing tool, the description covers the purpose, the key filters, the archived default, and the return's analytical value. No output schema exists, but the description sufficiently communicates what the agent will receive. There is no missing critical context needed to call 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 description coverage is 60%, with status and priority lacking descriptions. The description compensates by identifying these as filters and explaining the archived behavior. The branch parameter's nuanced values ('current', '', omit) are already documented in the schema, so the description need not repeat them.

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 ('List'), a clear resource ('epics for a project'), and the value-add ('task counts and completion stats'). This clearly distinguishes it from sibling tools like project_list, task_list, and the mutation-focused epic_create/epic_update/epic_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 gives clear context for when to use the tool: listing epics with filtering by status, priority, or branch, and controlling archived visibility. It does not explicitly name alternatives or state when not to use it, but the resource and purpose are unambiguous enough for an agent to select it correctly.

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?

Beyond annotations, it reveals that the update is partial, that setting status to 'cancelled' performs a soft-delete rather than a hard destruction, and that branch scoping can be pinned or cleared. These are exactly the behavioral details an agent needs. The description does not contradict the annotations: destructiveHint=false is consistent with soft-delete.

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 with no filler. The core action comes first, then the two non-obvious special behaviors (soft-delete and branch pinning) are stated in compact, actionable form.

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 update tool with eight parameters and no output schema, the description covers the essential invocation semantics: partial updates, soft-delete, and branch scope. It does not state what the response returns, but that is not strictly required to invoke the tool correctly; the key edge cases are documented.

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 general instruction 'Pass only the fields you want to change' adds meaningful semantics to all optional parameters, clarifying that omitted fields are left untouched. The description also explains the special branch values and the special 'cancelled' status beyond the raw schema, which is valuable given only 25% schema description coverage. It does not elaborate on obvious fields like name/tags/priority, but their names and types are self-explanatory.

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?

'Update an epic' names the exact verb and resource, and 'Pass only the fields you want to change' signals PATCH-style partial update rather than full replacement. This also separates it from sibling creation/listing/archiving tools, and the soft-delete and branch behavior add precision.

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 concrete operational conditions: status 'cancelled' is the soft-delete path, and branch accepts either 'current' for active-branch pinning or an empty string to clear. It does not explicitly name sibling alternatives or state when not to use it, but the update-vs-create distinction is clear enough from the verb and sibling names.

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 indicate destructiveHint=true and idempotentHint=true. Description adds no further behavioral context (e.g., permanence of deletion, soft-delete behavior). Adequate given annotation coverage.

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 5 words, no wasted text. However, could be slightly more informative while remaining 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 simple delete tool with one required parameter and no output schema, the description is sufficient. It lacks mention of return value or side effects, but annotations cover the destructive nature.

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% with parameter 'id' described as 'Note ID'. Description adds no extra semantics beyond 'by ID'. Baseline score for high 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 the action 'delete' and the resource 'note' with the method 'by ID'. It is unambiguous and distinct from siblings like note_list, note_save, note_search.

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 (e.g., note_save for updating, or archiving). No exclusions or prerequisites mentioned.

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

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description only needs to add behavior beyond that. It does add the sort-order behavior and implies a non-error path when no filters are supplied, but it stays silent on how filters combine, what happens on an empty result, and whether the result is truncated at the limit.

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 with no filler, the verb and resource are front-loaded, and the second sentence earns its place by disclosing sort ordering. The length is appropriate for a read-only listing 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?

With 6 parameters, 33% schema coverage, no output schema, and a close sibling (note_search), the description is too thin to fully support correct invocation. An agent is left to guess the semantics of the undocumented filters, how related_entity_id and related_entity_type interact, whether the limit caps the response, and when to prefer note_search over note_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?

Schema description coverage is only 33% (tag and project_id are documented; limit, note_type, related_entity_id, and related_entity_type are not). Since coverage is below 50%, the description must compensate, but it only says 'optional filters' without explaining any parameter's meaning, the relationship between related_entity_id and related_entity_type, or the effect of note_type on results. The description adds no semantic 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 states a specific verb ('List') and resource ('notes'), and adds useful behavioral detail about ordering ('sorted by most recent first'). It is clear on its own, but it does not differentiate itself from the note_search sibling, which is a meaningful gap given that both tools operate on notes.

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 word 'List' implicitly signals a browsing/listing use case as opposed to the query-style behavior implied by the sibling name note_search, but the description never states this trade-off or mentions alternatives. There are no explicit when-to-use or when-not-to-use instructions, so the agent must infer the appropriate context.

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 description discloses the key state-dependent behavior that passing an id updates an existing note while omitting it creates a new one. The annotations already mark readOnly=false, and the description adds meaningful context beyond that 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?

A single sentence carries the core operation, the create/update distinction, and the supported content categories with no filler. 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?

The schema covers required title/content, optional tags, note_type, and entity linking, while the description covers the core save behavior and the id-based update condition. The definition is sufficient for a straightforward note-save tool even though it does not describe the 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 71%, so the schema already explains most parameters. The description reinforces the id semantics and expands the note_type enum into practical categories like decisions, meetings, blockers, and releases, but it adds nothing about tags or related_entity 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 the exact operation, 'Create or update a note', and lists the content categories it supports. This clearly distinguishes it from sibling read, search, list, and delete note tools without needing to open their schemas.

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 id-based behavior is explicit: 'With id, updates; without, creates,' which tells the agent exactly how to choose the create versus update path. It does not explicitly name sibling alternatives, but the mutating verb and content scoping make its role as the write tool for notes evident.

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, destructiveHint=false, idempotentHint=true, covering the safety profile. The description adds the scope ('titles and content') but does not disclose details like search behavior (e.g., fuzzy matching) or performance considerations. With annotations present, this is adequate but 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, front-loaded sentence of 8 words, with no extraneous information. It efficiently communicates the core action.

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 three parameters (one enum), no output schema, and no description of return value or behavior, the description is incomplete. It fails to inform the agent about filtering by note_type, the default limit, or the structure of search results.

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 low (33%), with only 'query' having a description ('Search keywords'). The other parameters, note_type and limit, lack descriptions in both schema and tool description. The description does not explain how note_type filters results or that limit defaults to 20, so it 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 tool's function: searching across note titles and content by keyword. The verb 'Search' and resource 'note titles and content' are specific, distinguishing it from sibling tools like note_list or note_save.

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 instead of alternatives like note_list, nor any conditions or exclusions. The agent receives no help in deciding between similar note-related tools.

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 indicate this is a non-read-only, non-destructive operation. The description adds that projects are top-level containers, but does not disclose side effects, authentication needs, or rate limits. 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?

Two short sentences that are front-loaded with the action and provide a brief context. 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?

Despite good annotations and schema, the description omits return value information (no output schema) and does not describe default behaviors for optional parameters like status. A more complete description would mention created project details.

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 coverage is 100% with descriptions for all parameters. The description adds no additional parameter information beyond the schema, so baseline of 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?

The description clearly states the verb 'create' and the resource 'projects', and explains that projects are top-level containers. This distinguishes it from siblings like project_list and 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?

No guidance on when to use this tool versus alternatives like project_update or epic_create. The description does not mention 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.

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

Annotations confirm it's read-only and idempotent; description adds that it returns counts and percentages, providing useful 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?

Extremely concise single sentence that front-loads the key purpose and optional filter.

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 but description explains return values (counts, percentages). Lacks pagination details, but sufficient for a simple 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?

Single parameter status is fully described in schema; description only restates the filter option without adding new 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?

Clearly states it lists projects with epic/task counts and completion percentages, distinguishing it from other list tools like epic_list or task_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?

Mentions optional filtering by status, but lacks explicit guidance on when to use vs alternatives; however, the purpose is clear enough for correct selection.

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

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

Annotations already indicate the tool is not read-only and not destructive, with idempotency. The description adds value by disclosing the soft-delete behavior (setting status to 'archived') and the partial update semantics, which go beyond what annotations provide. No contradictions 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?

The description is comprised of two concise and front-loaded sentences, delivering key information without extraneous content. Every sentence adds value: the first states the primary action and partial update, the second explains the soft-delete use of the 'status' 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?

Given the tool's moderate complexity (5 parameters, partial update, soft-delete) and the absence of an output schema, the description covers the essential behavioral aspects. It is missing details about response format, error handling, or authentication, but the provided information is sufficient for basic 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 description coverage is low (20%), with only 'id' described. The description provides high-level guidance on partial updates and the effect of the 'status' parameter (soft-delete), but it does not elaborate on other parameters like 'name', 'description', or 'tags'. This partially compensates but insufficiently addresses the low 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 'Update a project' as the primary action, distinguishing it from creation or listing tools. It also specifies the partial update behavior and the special effect of setting status to 'archived' for soft-deletion, leaving no ambiguity about the tool's purpose.

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

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

The description advises to 'Pass only the fields you want to change,' implying partial updates, and explains soft-delete via status. However, it lacks explicit guidance on when to use this tool versus alternatives like project_create (for new projects) or other sibling tools, and does not mention prerequisites or restrictions.

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?

Beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description discloses two useful behavioral traits: each title becomes its own record and new subtasks are appended after existing ones. This gives the agent a concrete expectation of side effects; no contradiction with the annotations is present.

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, each contributing distinct information: what the tool creates, how titles map to records, and where the records are placed. The key verb and resource are front-loaded 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 3-parameter tool with fully described schema, the core behavior and placement semantics are covered. It does not describe the return value or the exact interaction of depends_on with multiple new subtasks, but these are relatively minor given the schema coverage and the absence of nested objects or enums.

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 the baseline is 3. The description adds value by explaining the titles array-to-record mapping and append behavior, which the schema alone does not fully convey. It appropriately leaves task_id and depends_on details to the schema, which already documents them.

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 verb and resource: 'Create subtasks (checklist items) for a task.' This clearly differentiates it from the sibling tools subtask_update, subtask_reorder, and subtask_delete, and from task_create, by saying it creates child checklist records rather than tasks or updated 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?

It communicates the clear usage context: add checklist items to an existing task, with titles passed as an array. It does not explicitly state when not to use it or name alternative tools, so it falls short of the strongest routing guidance, but the context is unambiguous.

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 annotations (destructiveHint=true, readOnlyHint=false, idempotentHint=true) already cover the core safety profile. The description adds no side-effect context such as permanence, cascade behavior, or error behavior, and its only extra behavioral claim—accepting a single ID—is false.

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 first sentence is short and front-loaded, but the second sentence does not earn its place: it repeats schema information and introduces an inaccuracy. A clean one-sentence description that just said 'Delete one or more subtasks by ID' would be better.

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 delete with no output schema, the core requirements are mostly covered by the schema, but the description introduces a conflicting input format and omits any return or error semantics. An agent cannot reliably know what happens after 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 schema fully documents ids at 100% coverage and explicitly says 'Always an array, even for one.' The description directly contradicts this by saying it accepts a single ID, which could cause an agent to send an integer instead of an array. This is actively harmful.

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 verb and target: 'Delete one or more subtasks.' This tells an agent exactly what the tool does and is enough to distinguish it from task_delete, note_delete, and comment_delete without inspecting 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?

No guidance is given about when to prefer this tool over alternatives such as task_delete, subtask_update, or subtask_reorder. There are no exclusions, prerequisites, or context cues beyond what the name implies.

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 mark it idempotent and non-destructive; the description adds the useful behavior that omitted IDs keep their relative order at the end. 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?

Two short sentences that front-load the action, then clarify the only non-obvious detail. 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 simple two-parameter mutation, this covers invocation semantics well. It does not discuss edge cases like duplicate or foreign IDs, or return values, but these are not critical for selecting 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 coverage is 100%, but the description adds the key array-order rule and explicitly instructs the caller to pass IDs in desired order, which is more than the schema's 'in order' note.

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 and resource: 'Reorder a task subtask list'. This clearly differentiates it from sibling subtask_create/update/delete tools.

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

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

The use case is implied by 'reorder', and the partial-order semantics tell the agent how to supply IDs, but it never states when not to use it or points to an alternative for moving or updating subtasks.

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 description adds meaningful behavior beyond the annotations: it explains that depends_on and blocks replace the existing set, that [] clears them, and that transitioning to started/finished with unmet prerequisites requires force. This aligns with the idempotentHint and does not contradict the readOnlyHint or destructiveHint 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?

Three short sentences are front-loaded with the core update purpose and packed with dependency and force semantics. The phrase 'blocks the inverse' is terse but economical; it earns its place without padding.

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 the main update targets, set-replacement behavior for both dependency arrays, clearing via [], and the force condition. It is slightly incomplete because it does not name sort_order explicitly or clarify the division of labor with subtask_reorder, but the remaining gaps are small.

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 only 43% schema coverage, the description compensates by explaining the semantics of depends_on/blocks replacement and the force requirement, and by summarizing title/status/position. However, it refers to 'position' rather than the actual sort_order property and leaves force policy details 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 states a concrete verb and resource ('Update a subtask') and enumerates the mutable aspects: title, status, position, plus depends_on/blocks. It does not explicitly distinguish itself from the sibling subtask_reorder, which also concerns position, and 'position' is not the schema's parameter name (sort_order).

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 call this tool versus alternatives such as subtask_create, subtask_reorder, subtask_delete, or task_update. The only conditional guidance is about force for unmet prerequisites, which is a behavior rule rather than a usage-selection rule.

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=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds minimal behavioral context beyond purpose, such as typical field changes, but does not disclose atomicity, partial-failure behavior, or any side effects. With annotations present, this is acceptable but not enriched.

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

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

The description is two sentences with zero wasted words. The core action 'Update multiple tasks at once' is front-loaded, and the examples are compact and illustrative. It earns a top score for efficiency and structure.

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 batch update tool with five parameters and no output schema, the description covers the primary use case but omits behavioral details like whether the update is atomic, what happens if some IDs are invalid, and how force interacts with the batch operation. The idempotent hint and force's schema description help, but the description alone leaves meaningful 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 description coverage is only 40% (ids and force have descriptions; status, priority, assigned_to do not). The description compensates somewhat by indicating 'changing status' and 'reassigning tasks', which maps to status and assigned_to. It does not mention priority or the nuanced force semantics, though force is already documented in the schema. Partial compensation earns a mid-range score.

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: 'Update multiple tasks at once.' It clearly differentiates from sibling task_update by emphasizing the batch aspect, and provides concrete examples of use cases (status changes, reassignments). This is unambiguous and immediately disambiguates from the singular update 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 gives clear context for when to use the tool: when several tasks need status changes or reassignment. It does not explicitly name task_update as the alternative for single tasks, but the 'multiple tasks at once' phrasing strongly implies the boundary. The guidance is effective though lacks an explicit when-not-to-use statement.

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 indicate this is a mutating, non-idempotent operation, and the description confirms the core behavior by stating it creates a task. It adds the parent-scope detail ('within an epic') but does not explain side effects, response behavior, or failure when an epic_id is invalid. There is no contradiction with the annotations.

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

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

Two short sentences with the core action front-loaded before context. Every phrase earns its place, and there is no redundant restatement of the parameter schema or 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?

Given 11 parameters, a nested source_ref object, and no output schema, the description is too sparse. It does not state what a successful creation returns, how to handle an invalid or missing epic_id, or which optional fields are commonly relevant when creating a task. The schema covers parameter details, but important behavioral and return context 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?

Schema description coverage is 73%, so most parameters are already documented in the schema. The description adds only the 'within an epic' context, which maps to epic_id but does not enrich the meaning of the other 10 parameters beyond their existing 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 starts with a specific verb and resource: 'Create a task within an epic.' This clearly separates it from task_update, task_batch_update, and subtask_create. The extra sentence 'Tasks are the primary unit of work' reinforces the tool's role and 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 gives useful context that tasks belong to an epic, and 'primary unit of work' hints at top-level task creation. However, it never explicitly says when to use this instead of subtask_create, task_update, or other related tools. There are no clear exclusions or alternatives, so usage guidance is only implied.

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?

Beyond the annotations, the description discloses the soft-delete behavior: the row is kept, hidden from listings, and restorable via task_restore. This directly explains why destructiveHint is false and adds operational context the annotations don't provide.

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 core meaning, then add the scope restriction and the restore behavior. Each sentence contributes new, non-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 mutation tool with no output schema, the description covers what mutates, what is preserved, the visibility effect, and the recovery path. The annotations already cover write/read-only and idempotence, so nothing essential 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?

Schema coverage is only 33%, so the description should compensate for undocumented parameters. It does not explain `deleted_by` or expand on `id`, and while `reason` has a schema description, the tool description adds no parameter-level 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?

The description names the exact action and resource ('Remove a task') and immediately clarifies it is a soft delete, which differentiates it from permanent-delete tools. It also names the inverse tool (task_restore), helping an agent distinguish this from restoration and other delete 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 explicitly scopes usage to 'todo' tasks and warns that further-along tasks should not be removed because their history matters. It does not name an explicit alternative tool for non-todo tasks, but the boundary is clear enough that an agent can decide against calling 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?

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds value by specifying the full scope of returned data (subtasks, notes, comments, dependencies), providing behavioral context beyond the safety profile.

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 fronts the purpose and efficiently lists included details. No superfluous 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 simple get tool with one parameter and no output schema, the description adequately explains the return scope. Could optionally mention error conditions or permissions, but annotations cover safety and idempotency.

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% for the single parameter 'id', which is described as 'Task ID'. The description does not add further meaning or constraints beyond the schema, so a baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Get') and resource ('a single task'), and clearly outlines the included details (subtasks, notes, comments, dependencies). This effectively distinguishes it from sibling tools like task_list or task_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 for retrieving a single task by ID, but does not explicitly state when to use it over alternatives like task_list. No exclusions or when-not scenarios are mentioned, relying on the user or agent to infer context from the sibling list.

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, idempotentHint, and non-destructive behavior, so the description adds useful output-shape details: subtask/dependency counts, compact rows, dropped nulls/metadata, 120-char description truncation, and branch scoping. 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?

Three dense sentences, each carrying new information: default scope, row compactness/truncation, and branch special value. The key scoping statement is front-loaded and there is 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 read-only list tool with 11 well-described optional parameters and safety annotations, this is nearly complete. There is no output schema, so a bit more explicit return-shape detail would be ideal, but the compact-row and count information gives enough context 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?

Schema description coverage is 82%, and the schema already explains branch semantics, sorting, project scoping, and defaults. The description adds little beyond restating the epic-scope behavior, so the baseline of 3 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?

States a specific verb and resource ('List tasks') and immediately clarifies scope: all epics when epic_id is omitted. It distinguishes itself from the sibling task_get by noting that rows are compact/truncated and pointing to task_get for full descriptions.

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?

Provides a clear pointer to task_get when full descriptions are needed, and explains the special branch='current' behavior. It does not enumerate exclusions, but for a read-only list with no required parameters the main alternatives are implicit and mostly covered.

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?

Discloses an important behavioral consequence beyond annotations: while locked, task_update refuses to change the description, while everything else remains editable. It also surfaces the safety-policy boundary about unlocking only on human request, which is valuable for agent behavior. No contradiction with idempotentHint=true or destructiveHint=false.

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 tightly written sentences carry the full behavioral contract: what the tool does, why it exists, and when unlocking is permitted. No filler 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 two-parameter tool with no output schema, the description fully covers the operational effect, the guardrail rationale, and the unlock policy. The annotations already cover idempotence and non-destructiveness, so nothing essential 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?

Schema description coverage is 100%, and both id and locked are already well documented inline. The description does not add new meaning to the parameters beyond restating the lock/unlock concept, so the baseline of 3 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?

Opens with a specific verb-resource pair: "Lock or unlock a task's description." It explains the practical effect (task_update refuses to change it) and distinguishes the tool from task_update, making its role in the task workflow 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?

Provides clear context for when locking is appropriate: "a guard against rewriting the spec when you meant to add a comment." It also gives an explicit rule for unlocking: only when a human asks, never to bypass the refusal. It does not name an alternative tool for adding comments, but the intent is 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?

Annotations already carry the key safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the description need not restate those. It adds the useful inverse relation to task_delete, but does not disclose consequences such as whether subtasks/comments are restored, error behavior for missing ids, 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?

A single front-loaded sentence, 'Restore a task removed with task_delete,' contains the action, resource, and precondition with zero filler. No restructuring or trimming is needed.

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 required id, no nested objects, no output schema) and the annotations covering idempotency and non-destructiveness, the description is nearly complete. It lacks only finer behavioral details like return value or effects on dependent objects, which are minor for this 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?

The schema provides only 'id: integer' with no description, and the description bridges that gap by implying the id identifies a task that was removed with task_delete. For a single-parameter tool this is sufficient to infer the parameter's meaning, though it does not spell out the id semantics explicitly.

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 immediately states a clear verb and object: 'Restore a task...'. It also names the sibling operation it reverses ('removed with task_delete'), which distinguishes it from other restore/crud tools like comment_restore without requiring schema inspection.

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 phrase 'removed with task_delete' gives a clear precondition and when to use the tool: to undo a prior task_delete. It does not explicitly enumerate alternatives or exclusion cases, but the task/comment split among siblings makes the intended use unambiguous.

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 indicate this is a mutating, non-destructive, idempotent operation. The description adds valuable non-obvious behavior: completing a task with unfinished subtasks is refused unless force is set. This goes beyond the annotations and helps the agent anticipate a blocking condition without contradicting the structured metadata.

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. 'Update a task' is somewhat redundant with the tool name, but the partial-update instruction and the subtask-force warning are each essential and earn their place. It is concise with minimal 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 tool with 14 parameters and no output schema, this description is notably incomplete. It captures the key update behavior and one refusal rule, but it does not explain return values, error behaviors, prerequisites such as needing an existing task id, or how this relates to sibling update tools. The agent would need to infer or discover important context elsewhere.

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 29%, and the tool description does not compensate for the many undocumented parameters. The phrase 'pass only fields to change' adds useful partial-update semantics, but it does not clarify fields like due_date format, assigned_to semantics, status transitions, or sort_order behavior. The description leans on mostly self-explanatory parameter names rather than providing needed 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?

The description states a specific verb and resource ('Update a task') and adds the partial-update nuance 'pass only fields to change.' It is clear but does not explicitly distinguish itself from siblings like task_batch_update or task_create, so it falls just short of full 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?

The description implies usage for updating a single task and changing only certain fields, but it never states when to prefer this over task_create, task_batch_update, or subtask_update. No exclusions or alternative conditions are provided, so the agent is left to infer the appropriate context.

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 indicate a non-read-only, non-destructive mutation. The description adds specific behavior—placeholder substitution and task creation—that enriches the agent's understanding without contradicting 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?

Two sentences front-load the core action and key behavior (placeholder replacement). No extraneous words; 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 tool with 3 params, no output schema, and nested objects, the description covers purpose and substitution behavior. Missing details like error handling or permissions are acceptable given context signals, though a note on idempotency would 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 coverage is 100% with clear descriptions for all three parameters. The description adds no new param-level detail beyond reinforcing the variable substitution mechanism, so baseline 3 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 clearly states the tool applies a template to create tasks in an epic. This verb-object structure distinguishes it from siblings like template_create, task_create, or epic_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 this tool is for converting a template into tasks within an epic, but does not explicitly contrast with alternatives like manually creating tasks or using other template tools. No when-not or exclusion guidance is provided.

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 indicate it is not read-only and not destructive. The description adds value by mentioning {variable} placeholders, which is a behavioral detail not in annotations. No contradictions observed.

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 front-loading the core purpose and key feature (placeholders). 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 no output schema, the description adequately covers the tool's purpose and usage. It hints at the integration with epics (template_apply). Could be improved by mentioning that the name must be unique (schema does), but overall 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 has 100% description coverage, so baseline is 3. The description reinforces the use of {variable} placeholders across parameters, adding context about dynamic values beyond what the schema provides.

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 ('Create') and resource ('reusable task template'). It distinguishes from sibling tools like template_apply and template_list by specifying that templates are for reuse and can be instantiated into epics.

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 concept of templates and placeholders, implying usage for defining reusable task sets. It provides context but lacks explicit guidance on when not to use or alternatives (e.g., comparing to subtask_create or task_create).

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 description aligns with annotations (destructiveHint=true) but adds no additional behavioral context beyond what annotations already convey.

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, complete sentence with no wasted words, achieving maximum 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 delete operation with one parameter and rich annotations, the description is adequate, though it could mention return values or side effects.

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 description does not add meaning beyond the schema's parameter description (Template ID). Baseline of 3 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 "Delete a task template." uses a specific verb (Delete) and a clear resource (task template), distinguishing it from sibling tools like template_create or template_apply.

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 not to delete a template that might be in use, or any prerequisites.

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 description adds no behavioral details beyond what annotations already provide (readOnlyHint, etc.). It does not mention scope or return 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?

Single, clear sentence 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?

For a simple list tool with no parameters and full annotations, the description is entirely sufficient.

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 is 100%. 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?

The description clearly states the action ('list') and resource ('task templates'), distinguishing it from sibling tools like template_create or template_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 this tool vs alternatives like epc_list or project_list. However, the tool's simplicity makes it obvious.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by enumerating the aggregate contents returned and framing it as a lightweight 'one call' overview, which is useful beyond the annotations 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 sentences deliver a complete picture with no filler. The main value proposition is front-loaded, the contents are listed compactly, and the usage tip and branch note are placed at the end without bloating the description.

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 appropriately takes on the job of describing what the tool returns, and it lists the main sections clearly. It is sufficient for a read-only dashboard with optional parameters, though a slightly more explicit note about the overall response shape would make it 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 description coverage is 100%, so the schema already documents all three parameters thoroughly. The description only restates the branch='current' behavior already present in the schema, adding no genuinely new semantic information beyond the parameter 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 identifies the resource ('full project overview') and the specific data included: project, epics with task counts, stats, blocked/overdue tasks, recent activity, and notes. This distinguishes it from more granular siblings like task_list, project_list, and activity_log by framing it as an aggregated 'one call' dashboard.

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 clear situational guidance: 'Best first call when starting work.' This tells an agent when to prefer this tool, though it does not explicitly name alternatives or state when NOT to use it, so it falls just short of full routing 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, indicating a safe, idempotent read operation. The description adds valuable context about the export's content (all entities included), going beyond the structured data. It does not describe potential size limits or rate limits, but given the annotations, the bar is lower.

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 concise sentences, each adding value. The main action is front-loaded, and the supporting sentences clarify scope and use cases without redundancy. 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?

Given the tool's simplicity (one optional parameter, read-only, idempotent), the description is adequate. It specifies output format and included content, which compensates for the lack of an output schema. However, it could mention intended output structure or size considerations 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?

Schema description coverage is 100%: the only parameter, project_id, is fully described in the schema. The description adds no additional parameter information. Per guidelines, with high coverage, baseline is 3.

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 (export), the resource (full project), and the format (nested JSON), with a detailed list of included elements. This specificity implicitly distinguishes it from sibling tools like tracker_import or tracker_session_diff, making the purpose 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?

The description explicitly gives usage context: 'Useful for backup, migration, or sharing.' This provides clear context for when to use the tool, though it does not list alternatives or when not to use it, which would earn 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?

Beyond annotations, description reveals it creates new IDs, remaps references, and uses a transaction for atomicity. No contradictions 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?

Three concise sentences, 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?

Given no output schema and single parameter, description adequately covers behavior. Could mention prerequisites (e.g., valid JSON format) but sufficient.

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 parameter description already states it expects a full export JSON. Description adds no new parameter-level meaning beyond that.

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 imports a project from JSON, matching the tracker_export format. This distinguishes it from siblings like tracker_export and project_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?

Implies usage when importing a previously exported project, but lacks explicit guidance on when not to use or alternatives. Context is 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?

Annotations (idempotentHint=true) are supported by description's conditional logic. Description adds context beyond annotations: explains that creation only happens if DB is empty, and existing projects return info. No contradictions.

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

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

Two sentences efficiently convey purpose, conditional behavior, and parameter usage. No redundancy, front-loaded 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 simple parameters, no output schema, and good annotations, the description covers both scenarios comprehensively. No missing information for an agent to decide or 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 coverage is 100% with clear parameter descriptions. Description restates that project_name is only used if DB empty, but adds no new semantics beyond schema. Adequate but no extra 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 tool initializes a tracker for a project, with explicit conditional behavior: creates if DB empty, returns info if exists. Distinguishes from siblings like project_create and project_get by handling initialization logic.

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?

Provides clear context on when to use (initializing a tracker). Does not explicitly exclude alternative tools, but the conditional behavior makes usage clear. Among siblings, it's distinct from tracker_dashboard, etc.

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?

Beyond the readOnly/idempotent annotations, the description discloses that results are categorized previews rather than full content, which is a meaningful behavioral trait. It also sets the expectation that full text must be fetched through other tools, adding transparency about the tool's scope.

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 action and scope in the first sentence, and the output type plus routing alternatives in the second. Every clause earns its place, and the most decision-relevant details are 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?

With no output schema, the description gives enough shape by saying results are categorized previews and by pointing to full-text alternatives. Combined with fully documented parameters and safe read-only annotations, this is a workable definition, though the exact preview structure is left 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 100%, so all six parameters including `limit`, `branch`, `project_id`, `entity_types`, and `include_archived` are already documented there. The description only reinforces the query-keyword behavior and adds no new parameter-level meaning beyond the schema.

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

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

The description clearly identifies a search behavior ('Search projects, epics, tasks and notes by keyword') and a specific output type ('categorized previews'), so the tool's core purpose is unambiguous. It does not explicitly distinguish itself from the sibling `note_search`, which also covers note searching, so it stops short of full 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?

The description gives clear usage context: use this for keyword search across multiple entity types when previews are sufficient. It also gives an explicit when-not and alternative: 'use task_get or note_list for full text.' It does not address alternatives like dedicated note or project search tools, but the guidance provided is actionable.

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 mark it read-only and idempotent. The description adds useful behavioral details: aggregated summary with counts and highlights, no side effects mentioned. 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?

Three concise sentences. Purpose, return format, and usage advice are front-loaded 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 no output schema, the description fully explains what is returned. Parameter is well-covered. The tool's purpose and context (session start) are clear.

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 already provides full description for the only parameter (ISO 8601 datetime). The description does not add extra semantic nuance 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 returns changes since a timestamp, with specific outputs (counts, highlights). It distinguishes itself from sibling tools like activity_log by focusing on session-level summary.

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 advises calling at session start to understand previous changes. Does not list alternatives but context is clear enough for most agents.

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