mcptask.online

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the write-but-non-destructive profile is covered. The description adds little beyond that: no mention of download behavior for file_url, size/type limits, whether existing attachments are affected, or required permissions.

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

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

A single well-formed sentence with the action front-loaded and no filler. It is efficient, though so terse that it omits the mode-selection context an agent would benefit from.

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 three alternative content-supply parameters and no output schema, the description should clarify which input mode to pick and what the caller gets back (an attachment reference). Neither is addressed, though the schema carries the parameter burden.

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 each of the six parameters is already documented, including the three mutually exclusive upload modes. The description contributes no additional meaning about those modes or the optionality of file_name, so baseline 3 applies.

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

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

States a specific verb and resource (upload a file attachment) plus the exact target (an existing task/story/piece), so an agent can distinguish it from GetAttachmentTool. The word 'directly' gestures at a different upload path (CreateUploadUrlTool) but doesn't name it, leaving some ambiguity about which tool is the right one.

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 ('directly to an existing task') but never states when to prefer this over CreateUploadUrlTool or the two-step signed_blob_id flow. No preconditions or exclusions are given, so the agent must infer the routing decision.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds that attaching a file is optional, but says nothing about how the three mutually exclusive attachment paths behave (server-side download vs base64 vs pre-uploaded blob) — that context lives only in the schema property text.

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

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

One sentence, front-loaded with the primary action, no filler. Appropriate for the amount of unique information it conveys.

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

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

For a 7-parameter mutation tool with three interchangeable file-input modes and no output schema, the description omits the attachment-mode selection rule, whether an attachment can be combined with plain text, and what is returned. The schema patches parameter detail, but the overall behavior story is thin.

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 carries the parameter detail; the description correctly flags that the attachment parameters are optional, which is the main semantic fact an agent needs at the top level. Baseline 3 plus a bit for calling out optionality of the 4 non-required attachment params.

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: 'Add a note/message to a task', plus the attachment capability. An agent can identify the operation directly, though the overlap with sibling AddAttachmentTool is not addressed.

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 versus AddAttachmentTool, or when to use the three different file-supply mechanisms (file_url, file_content, signed_blob_id). The agent must infer usage entirely from the schema.

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 the mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the safety question is answered structurally. The description adds nothing beyond that: it does not say whether blocking affects downstream tasks, notifies anyone, requires a reason, or is reversible, which are the behavioral facts an agent needs for a state-changing task operation.

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

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

A single short sentence with no waste and the action front-loaded. It is slightly under-specified rather than bloated, which is the better failure mode here.

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?

This is a state-mutating tool with no output schema and no annotations describing side effects, yet the description omits what blocking does to the task, its dependents, or the resulting state. The ambiguity against ManageBlockerLinksTool is also left unresolved, leaving real gaps for an agent to guess at.

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 the enum and each parameter documented inline, so the schema carries the parameter burden. The description adds no extra semantics (e.g., what a 'reason' is used for or what task_relative_id is relative to), which is the baseline-3 case.

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 pair (block/unblock) and resource (task), so the core action is unambiguous. However, it offers no differentiation from the sibling ManageBlockerLinksTool, which an agent could easily confuse with this one, and the qualifier 'that cannot be completed temporarily' is vague about 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?

There is no guidance on when to block versus unblock, no prerequisites, and no mention of the closely related ManageBlockerLinksTool sibling. The agent must infer usage entirely from the enum in the schema.

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 this is a non-readonly, non-destructive write, so the safety profile is covered. The description adds 'full authorization controls' (too vague to be actionable) and describes the blocked_by dependency semantics, though those semantics are largely restated from the schema. It never states what is returned or whether authorization failures surface as errors.

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

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

Two tightly written sentences, front-loaded with purpose before the dependency rule. The second sentence is largely recoverable from the schema, so it does not fully earn its place, keeping this just below a 5.

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 15-parameter mutation with no output schema, the description omits what the caller gets back (e.g., the new piece's relative id), how authorization failures manifest, and any prerequisites beyond a valid account_code. The schema carries the parameter burden well, but the surrounding behavior is thin.

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 15 parameters are already documented, including the additive/all-or-nothing behavior of blocked_by_relative_ids. The description's dependency sentence repeats that schema text rather than adding new meaning (e.g., ordering, idempotency, or how to resolve relative ids). Baseline 3 applies.

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

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

States a specific verb (Create) and resource (work items: Tasks, Stories, Epics, Recurents) in the named system, and is easily distinguished from siblings like UpdatePieceTool or ListPiecesTool. An agent knows immediately what this tool produces.

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

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

Usage is implied by the create semantics, but the description never says when to prefer this over UpdatePieceTool for existing pieces, nor does it name any alternative for dependency management (ManageBlockerLinksTool is only mentioned for removal, not for initial linking). No explicit when-not conditions.

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, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds valuable behavioral context by noting the URL is 'short-lived' and the blob id is 'signed', and that the upload goes directly to storage. It does not mention rate limits or error conditions, but this is reasonable given the 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?

The description is a single, front-loaded sentence that efficiently conveys the tool's purpose and key outputs. Every phrase adds value without redundancy.

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

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

Given the fully documented schema and existing annotations, the description provides sufficient context: what the tool returns (URL and blob id), their short-lived nature, and their intended use. It does not explain how to use the URL (e.g., HTTP method) or detail error cases, but these are minor gaps for a tool with rich structured data.

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

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

Schema description coverage is 100%, so all parameters are already documented in the schema. The description does not add any parameter-level semantics beyond what the schema provides, which is the baseline expectation 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?

The description states a specific verb ('Returns') and two specific resources ('short-lived URL' and 'signed blob id'), and clarifies their purpose: uploading a file directly to storage and attaching it to a piece or message. This distinguishes it from sibling tools like AddAttachmentTool, which likely consumes the blob id rather than producing it.

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

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

The description implies when to use the tool (you need an upload URL and blob id) but does not explicitly state when to use it versus alternatives, nor does it mention prerequisites or exclusions. The usage context is only implied by the stated purpose.

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 openWorldHint=false, so safety is covered. The description adds useful behavioral context that filters are scoped to the authenticated user's role, which is important for authorization expectations.

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 zero waste. The export capability is front-loaded, followed by the scoping constraint, making it easy to parse.

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 export tool with no output schema, the description does not explain how results are returned (file, content, link, etc.) or mention the sibling for discovering filter options. The schema and annotations cover much, but return behavior and alternative tooling remain 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 100%, so the baseline would be 3. However the description mentions a 'workers' filter that is not present anywhere in the input schema, which is misleading about available 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 states a specific verb ('Exports') and resource ('timesheet report') and names the output formats. It does not differentiate itself from the sibling ListTimeSheetReportOptionsTool, but the core purpose is unambiguous.

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

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

The description gives no explicit when-to-use guidance, no exclusions, and does not mention the related ListTimeSheetReportOptionsTool for discovering filter values. The role-scoping note provides some context but not usage instructions.

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 openWorldHint=false, so the safety profile is covered. The description adds useful scope information by enumerating what is returned (users, permitted projects, permitted companies), which helps the agent anticipate a composite read. It says nothing about authorization requirements, response size, or pagination, so it only modestly exceeds the annotation baseline.

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 fragment with zero filler; the keying parameter and the returned content are stated immediately. It loses a point only because the fragment lacks an explicit verb, making it slightly less self-contained than a full sentence would be.

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

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

For a one-parameter read-only tool with annotations covering safety and no output schema, the description supplies enough: the resource, the key, and the shape of the returned content. The absence of output schema means return values are not fully specified, but the enumeration of content categories largely compensates.

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

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

Schema coverage is 100% and the single account_code parameter already carries a description with examples ('bcp', 'jchsoft'). The description adds only that the code selects an account workspace, which is implicit from the schema. With one parameter and full schema coverage, the 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 names a specific resource (the account workspace) and enumerates the content it exposes: attributes, account-level users, permitted projects, and permitted companies. It is clearly distinguishable from GetProjectTool, GetPieceTool, and GetCurrentUserTool by its account-code scoping. It is a noun phrase rather than an explicit verb, but the retrieval intent is unambiguous.

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

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

The only usage signal is the phrase 'by account code', which implies the lookup key but gives no guidance on when to prefer this over GetProjectTool or GetCurrentUserTool, nor any prerequisite or exclusion. An agent must infer the call context entirely.

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 openWorldHint=false, so safety is covered. The description still adds real behavioral value by disclosing the return mode: metadata plus a download URL rather than inlined binary content.

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

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

A single front-loaded sentence that leads with what is returned and uses the parenthetical only to disambiguate the response format. No wasted words.

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

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

With no output schema, the description carries the burden of describing the return value, and it does so at a high level (metadata + download URL). It could say slightly more about what the metadata contains, but for a simple 3-parameter read operation with full annotations this is close to 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 description coverage is 100% – account_code, piece_relative_id, and attachment_id are each documented in the schema, including the useful 'not relative_id' disambiguation on attachment_id. The description adds nothing about parameters, so the baseline 3 applies.

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

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

States a specific verb (get) and resource (attachment metadata + direct download URL) scoped to a piece attachment. This distinguishes it cleanly from AddAttachmentTool, the only other attachment-related sibling.

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

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

Usage is implied rather than stated: the parenthetical 'avoids inlining binary content' hints at when to prefer this over fetching raw content, but no alternative tool or condition is named. No explicit when/when-not guidance is given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds value beyond them by disclosing what the call returns — including per-Company-role values like respect_working_hours and hour_goal — which matters because there is no output schema. It does not state authentication prerequisites explicitly, though the resource name implies 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?

A single front-loaded sentence that enumerates the returned fields with no filler. Every clause maps to real content an agent would want before calling.

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 parameters and no output schema, the description carries the full burden of describing returns, and it does so field-by-field. It is nearly complete; a note that the call requires an authenticated session (and what happens otherwise) is the only visible 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 tool has zero parameters, so the schema imposes nothing to document. The description correctly spends its words on output content instead, which is the only meaningful semantic detail available for a parameterless call.

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 resource precisely ('current authenticated user') and enumerates the payload (profile, account codes, today's working hours, respect_working_hours flag), so an agent can tell it apart from GetAccountTool and the other Get* siblings. It stops short of explicitly stating the distinction from GetAccountTool, which is the nearest neighbour.

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?

There is no explicit when-to-use or when-not-to-use guidance, but the tool takes zero parameters and its scope ('current authenticated user') implies its own trigger condition unambiguously. Usage is inferred rather than stated.

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 the safe read-only profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description goes beyond them by disclosing the ordering algorithm (priority, errors first, oldest within priority, blocked skipped) and clarifying that exclude_relative_ids is per-call and does not mutate piece state.

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 the core purpose front-loaded and the ranking rules packed into a compact parenthetical that genuinely affects which subtask is returned. Slightly dense but nothing is wasted.

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

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

For a read-only, three-parameter tool the safety and selection behavior are covered, but with no output schema the description never says what is returned when no subtask remains (empty/null/error) or what shape a returned subtask takes. That is a meaningful gap for a tool whose whole job is picking one item.

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 three parameters are documented in the schema and a baseline of 3 applies. The description restates the exclude_relative_ids per-call semantics rather than adding new syntax or format detail, so it does no better than the schema it duplicates.

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 ('Get the next subtask to work on inside one Story') and scopes it to a single Story, which implicitly separates it from the sibling GetNextTaskTool. It never names that sibling or any alternative explicitly, so the differentiation is inferred rather than stated.

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

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

Usage is implied by 'the next subtask to work on' and by the selection algorithm, which tells the agent this is a work-queue-picking tool. There is no explicit when-not guidance or reference to GetNextTaskTool, so an agent must infer which of the two 'next' tools applies to its situation.

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, openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral detail beyond annotations: the priority ordering (errors first, oldest within priority) and that exclude_relative_ids is per-call and does not mutate piece state.

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 dense sentence with the core action front-loaded and qualifiers trailing. Every clause earns its place, though the parenthetical ordering rule and the filter/skip note in one sentence makes it slightly dense rather than optimally scannable.

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

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

There is no output schema, so the description carries some burden to describe what is returned, yet it never states the return shape (a piece/story object, or null when nothing matches). Combined with the missing sibling differentiation, this leaves a modest gap for an agent deciding how to consume the result.

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 well, including the per-call semantics of exclude_relative_ids. The description restates the project filter and skip behavior in prose but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Get the next task or story to work on') and even specifies the selection algorithm (highest priority, errors first, oldest within priority). However, it does not differentiate itself from the close sibling GetNextStorySubtaskTool, which an agent might reasonably confuse it with.

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 via 'Optionally filter by project' and the exclude_relative_ids note, giving the agent a sense of the knobs. It never states when to prefer this over GetNextStorySubtaskTool or ListPiecesTool, nor any exclusions, so usage 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description usefully adds a behavioral constraint not present in the annotations — the result is capped at the most recent 50 entries — but says nothing about how to retrieve older entries, whether pagination exists, or what authentication/account scoping implies.

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

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

A single front-loaded sentence that identifies the resource, the keying parameter, and the result limit with no filler. Every clause 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?

With no output schema, the description carries responsibility for describing return values; it conveys the entity and the 50-entry cap but not the shape of an effort entry or how to page beyond the most recent 50. It is minimally viable for a simple two-parameter read tool.

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

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

Schema description coverage is 100%, so both account_code and piece_relative_id are already documented in the schema. The description's phrase 'by its relative ID' merely echoes the schema field rather than adding format, range, or lookup guidance, so the baseline 3 applies.

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

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

The description names a specific resource (effort/time-tracking history) tied to a specific entity (a piece identified by relative ID), which is clearly distinct from GetPieceTool, ListPiecesTool, or SearchPiecesTool. It stops short of explicitly contrasting itself with those siblings, but the verb+resource pairing is unambiguous.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no pointer to an alternative such as GetPieceTool for general piece data or ListTimeSheetReportOptionsTool for reporting. The agent must infer from the resource name alone when this tool is appropriate.

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 openWorldHint=false, so the safety profile is covered. The description adds real value beyond them by disclosing the payload composition – subtasks, messages and attachments are included, which is beyond what the annotations state.

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

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

One sentence, front-loaded with the verb and resource, with the payload enumeration trailing. There is no filler or duplication.

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

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

There is no output schema, so the description's enumeration of returned content (subtasks, messages, attachments) does useful work in setting expectations. It stops short of describing depth limits (e.g., how many messages or whether attachments are metadata only), but is sufficient for a simple two-param read tool.

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

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

Schema description coverage is 100%, so both parameters are already documented in-schema, giving a baseline of 3. The description's emphasis on 'relative ID' mildly reinforces the piece_relative_id semantics but adds nothing about the account_code format that the schema lacks.

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 ('Read comprehensive details') and resource ('a single piece') plus a clear lookup key ('by its relative ID'). The word 'single' cleanly separates it from sibling list-style tools like ListPiecesTool and SearchPiecesTool.

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 'of a single piece ... by its relative ID' implies when to call it (when you have an ID and want full detail rather than a list), but no alternative or exclusion is named. An agent must infer the ListPieces/SearchPieces boundary itself.

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 openWorldHint=false, so the safety profile is covered. The description adds genuine value beyond that by disclosing the composition of the result (options, users with roles, task summary), which matters because no output schema exists. It stops short of describing error behavior when the ID is invalid.

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 with no filler; the scoping key comes before the payload list. It is efficient, though the opening 'Extended project information' is slightly vague about what 'extended' means relative to the plain project tool.

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

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

For a two-parameter read-only tool with no output schema, the description supplies the essentials: what is fetched, by which key, and roughly what comes back. Missing only error semantics and how to discover the relative ID, which are minor against a fully documented schema and read-only annotations.

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

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

Schema description coverage is 100%: both account_code (with examples 'bcp', 'jchsoft') and project_relative_id are documented in the schema itself. The description's 'by relative ID' adds no meaning beyond the schema's 'Relative ID of the project', so the baseline 3 applies.

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

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

States a specific verb and resource ('project information') scoped to a lookup 'by relative ID', and enumerates the payload: options, users with roles, task summary. It does not, however, distinguish itself from sibling tools like ListProjectsTool or GetProjectTreeTool, so an agent must infer the boundary.

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 'by relative ID' implicitly tells the agent this is a per-project fetch keyed on a relative identifier, which distinguishes it from list-style siblings. But there is no explicit when-to-use/when-not guidance and no alternative tool is named for cases where the agent lacks a relative ID or wants the full tree.

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 readOnlyHint, destructiveHint, and openWorldHint, so the safety profile is handled. The description goes further by disclosing the return structure (hierarchy levels and node contents), which matters because there is no output schema. It omits behavior on very large trees, truncation, or depth limits.

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

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

Two tight sentences, front-loaded with the resource and then the return shape; no filler. It is aggressively terse but every clause carries information, with only mild loss from the telegraphic style.

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, two-parameter tool with full schema coverage, the description plus annotations cover the essentials, and the node-field listing partially substitutes for the missing output schema. It is still silent on tree depth, result size, and ordering behavior.

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

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

Schema description coverage is 100%, with both account_code and project_relative_id documented in-schema, so the baseline is 3. The description adds no syntax, format, or lookup guidance for either parameter.

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

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

States a specific resource (a project's hierarchical tree) and pins the shape precisely: Root -> Epic -> Story, with compact node fields. An agent knows exactly what this returns. However, it never differentiates itself from the sibling GetProjectTool, which serves a similar resource, so it stops 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?

There is no when-to-use guidance, no prerequisites, and no named alternative. With GetProjectTool and ListProjectsTool present in the sibling set, the agent is left to infer whether to call this for hierarchy vs. flat project details.

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 openWorldHint=false, so the description doesn't need to repeat safety. It adds that the output is markdown, but does not mention size, caching, or whether it's static documentation—modest added 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?

A single, front-loaded sentence with zero waste; every word contributes to purpose and format.

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

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

For a zero-parameter, read-only documentation tool with full annotation coverage and a clear stated return format, the description is largely complete. It doesn't need to explain return values beyond format since no output schema exists, though a note on whether it covers all server features would help.

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

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

Zero parameters, so per the rubric the baseline is 4. The description correctly implies no inputs are needed and adds that the result is markdown.

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 (get) and resource (usage guide), clarifies scope as 'how to use this MCP server', and specifies the return format (markdown). Clearly distinguishes itself from every sibling tool, which all operate on pieces, tasks, or projects.

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

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

The parenthetical '(how to use this MCP server)' implies it should be called when the agent needs orientation to the server, but it doesn't explicitly say when to use this vs. just proceeding with other tools or when it's unnecessary.

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 openWorldHint=false, so the safety profile is fully covered. The description's pagination bounds (1-50, default 10) merely restate the schema's 'size' description, so it adds little behavioral context beyond structured fields, though nothing is contradicted.

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 no filler; the core purpose is front-loaded before the pagination detail. Minor redundancy with the schema's size description keeps it from a 5.

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

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

For a simple read-only, closed-world list tool with one required parameter and full schema coverage, the definition is nearly complete. The only gap is silent on return shape (item list plus pagination metadata), which matters slightly since no output schema exists.

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% – all three parameters (page, size, account_code) are documented in the schema, including defaults and the 1-50 range. The description repeats the size range only, adding no syntax or format meaning beyond the schema, so the baseline 3 applies.

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

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

Specific verb+resource: 'Paginated list of doable pieces (Tasks, Stories, Recurents) for an account' names the operation and clarifies the domain vocabulary of 'pieces'. It does not, however, distinguish itself from the sibling SearchPiecesTool or GetPieceTool, leaving the agent to infer the boundary.

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

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

Usage is only implied: it lists pieces for an account, paginated. There is no statement of when to prefer this over SearchPiecesTool, nor any exclusion or prerequisite beyond the required account_code. Adequate but with a clear routing gap given a near-identical 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 declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact beyond them: results are limited to the current user's projects rather than all projects in the account. It says nothing about pagination, ordering, or result size, which matters for a list tool.

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

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

A single sentence with no filler, and the scoping qualifier is placed before the resource it modifies. It is appropriately sized for a one-parameter list tool, though it is terse to the point of leaving the usage question entirely unaddressed.

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

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

For a simple read-only, single-parameter list tool with full schema coverage and clear annotations, the definition supplies what an agent needs to select and invoke it; no output schema exists so return-value detail is not owed. The only real omission is any hint about result volume or pagination, which is a minor gap rather than a blocking one.

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

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

Schema description coverage is 100% and the single account_code parameter is documented in the schema with format examples ('bcp', 'jchsoft'). The description's phrase 'under an account' merely restates that the parameter scopes the query, adding no syntax or semantics beyond the schema, so the baseline 3 applies.

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

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

The description pairs a specific verb (List) with a specific resource (projects) and scopes it to the current user's projects under an account, which separates it from GetProjectTool (single project) and ListPiecesTool. It does not name or contrast with those siblings explicitly, so it stops 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as GetProjectTool or GetProjectTreeTool. The only usage signal is the implicit 'under an account' scope, which the required account_code parameter already conveys.

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, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds genuinely new context beyond that: returned values are scoped to the authenticated user's role, which tells the agent results are authorization-dependent and may differ per caller.

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 zero filler, and the core purpose is front-loaded before the role-scoping caveat. Every clause carries information an agent can use.

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

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

With no output schema, the description does the work of naming what comes back (filter categories plus layout options), and read-only annotations cover the safety profile. Minor gaps remain around the exact response shape, but nothing needed to call the tool correctly 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% (to/from ISO dates with defaults, account_code with examples), so the schema already carries parameter meaning. The description's enumeration of filter categories refers to output, not inputs, and adds no syntax or constraint detail beyond the schema, making the baseline 3 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 ('Lists available filters for the timesheet report') and enumerates the filter categories returned (date range, companies, projects, workers, layout options). It is distinguishable from ExportTimeSheetReportTool by the fact it returns filter metadata rather than a report, though it never names that sibling explicitly.

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

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

Usage is only implied: an agent can infer this is a discovery tool to call before ExportTimeSheetReportTool to learn valid filter values. There is no explicit when-to-use, when-not-to-use, or alternative named, so it stays at implied 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 this is a non-read-only, non-destructive, closed-world write. The description adds one genuinely new behavioral fact — that task state is managed automatically — but leaves it unexplained (does progress_percent=100 close the task? is the entry reversible?). No auth, validation, or error behavior is disclosed.

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 short sentence with no wasted words, and the core action is front-loaded. The vague trailing phrase 'automatic task state management' is the only slack in an otherwise tight statement.

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 write tool with five fully documented parameters and a clear safety annotation set, the basics are covered. However, no output schema exists and the description neither describes the response nor explains the promised automatic state transition, which is the most consequential behavior for an agent to predict.

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 every parameter (including the 0-100 range on progress_percent and example account codes) is documented in the schema itself. The description adds no format or constraint detail beyond that, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('Log work progress'), so an agent immediately knows this writes a progress entry. The trailing clause hints at a side effect on task state, but no sibling (e.g., UpdatePieceTool) is named to disambiguate when this is preferred over a general 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?

There is no when-to-use guidance, no prerequisite (e.g., account_code/task_relative_id must already exist), and no alternative named. Neither when this should be used instead of UpdatePieceTool nor what happens after logging is stated.

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 destructiveHint=true and openWorldHint=false, so safety is partly covered. The description adds genuinely new context beyond annotations: the whole call is rejected if any id in an 'add' batch is invalid, which is critical for an agent to know before batching.

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, zero filler, with the operation stated first and the batch constraint second. Nothing is buried or repeated unnecessarily.

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 4-param mutation tool with no output schema, the description plus annotations plus a fully documented schema cover the essentials, including the destructive nature and atomic failure mode. It stops short of describing the success return shape or whether removals are reversible, but those are minor given the annotation coverage.

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 account_code, piece_relative_id, action, and the add/remove semantics of blocker_relative_ids in detail. The description restates the atomicity rule but adds no syntax, format, or identifier 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 names a specific verb pair (add/remove) and resource (blocked_by links on a piece), which is more precise than the tool name alone. It does not differentiate itself from the sibling BlockTaskTool, which plausibly overlaps in intent, so an agent must infer the boundary.

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

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

Usage is implied by the verb and the add/remove action enum, but there is no explicit when-to-use guidance or routing to alternatives such as BlockTaskTool or UpdatePieceTool. The batch-failure note hints at when the tool is appropriate for bulk edits but never states it as 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/openWorldHint/destructiveHint, but the description adds real behavioral value by disclosing the return shape: 'compact rows, counts_by_state over the whole filtered set' — clarifying that counts span the full filtered set, not just the page. It does not discuss pagination limits, but the schema covers those.

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?

Core verb and scope are front-loaded in the first clause, and the second sentence delivers the usage directive. Dense but efficient with no filler, though the semicolon-heavy first sentence packs several ideas together.

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 15-parameter read-only search with no output schema, the description covers the filterable axes, the project scoping, and the result shape (compact rows plus counts_by_state). Nothing critical is missing, though pagination/sort behavior is left entirely to the schema.

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

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

Schema description coverage is 100%, so all 15 parameters are already documented (including the 'open' state shorthand and assigned_user_id=0 semantics). The description restates the filter dimensions but adds no format or syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (search) and resource (pieces of ONE project) plus the filterable dimensions (type, state, assignee, author, text). The 'ONE project' scoping and 'no account-wide search' framing help distinguish it from a broader listing, but no sibling tool is named explicitly.

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

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

Gives a clear use case: 'Use for filtered questions such as state, assignee, author or text.' This tells the agent when the tool is the right pick, though it never names the alternative (e.g., ListPiecesTool) or states an explicit exclusion.

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 the write/destructive/open-world profile, and the description adds genuinely new behavioral facts: a hard rate limit of 3/day, refusal of suppressed and already-contacted recipients, no footer/logo/tracking injection, and dedupe semantics. That is useful operational context beyond the annotation set.

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 dense sentences with zero filler; the core action leads and the constraints (rate limit, refusals) follow immediately. Every clause carries 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 7-parameter mutation tool with no output schema, the description covers the essential behavioral envelope (rate limit, refusal rules, sender identity, formatting behavior). A note on what a successful send returns or whether the send is asynchronous 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% and the schema itself explains each field in detail, including dedupe_key idempotency and body_text preference. The description only echoes 'plain text preferred' and the dedupe_key concept, 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?

States a specific verb and resource ('Send a personalized outreach email') along with the sending channel ('from your own address through the outreach pipeline'), which is precise enough to distinguish it from generic siblings like AddMessageTool. It stops short of explicitly naming an alternative tool, so it does not fully meet the 5 bar.

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

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

Usage context is implied by 'outreach pipeline' and the refusal conditions tell the agent when a call will be rejected, but there is no explicit when-to-use vs. alternative guidance (e.g., versus AddMessageTool for non-outreach messages). Adequate but clearly gapped.

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 goes beyond the annotations by explaining that only provided attributes are changed, that a before/after diff is returned per touched attribute, and the all-or-nothing rejection behavior for blocked_by. The destructiveHint is true but the description clarifies the partial-update nature so the agent knows it is not a full overwrite. It doesn't mention permissions or rate limits, but the key behavioral traits for a mutation are disclosed.

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

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

Four sentences, each earning its place: purpose, partial-update semantics, return value, and dependency-specific behavior. Front-loaded with the main action and scope.

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

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

The description covers the critical aspects: piece types, partial update, return value, and the nuance of blocked_by. With no output schema, the description explains the return briefly. However, it doesn't mention that some attributes are type-specific (Epic-only for_errors, Task-only task_type_code) which is in the schema but could be highlighted. Still, the schema covers it, so the 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 coverage is 100%, so the schema already documents all 12 parameters thoroughly. The description adds the concept of additive blocked_by links and that they are refused if already linked, which is not in the schema's description. For the other parameters, the description doesn't add beyond the schema, 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 states a specific verb (Update) and resource (Task/Story/Epic/Recurent piece) and identifies the key (relative_id). It distinguishes itself from CreatePieceTool and the read siblings by naming the exact piece types and the update semantics.

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

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

The description makes clear that it updates existing pieces and that only passed attributes change, implying partial-update semantics. It also points to ManageBlockerLinksTool for removal of blocking links, which is a clear alternative for that sub-operation. However, it does not explicitly say when to prefer this over ManageBlockerLinksTool for adding links (though the schema for blocked_by explains it).

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