Madda Tasks

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

Annotations only declare the safety profile (non-read-only, non-destructive, non-idempotent); the description adds real behavioral context beyond them: the permission floor ('Any team role'), a hard length limit, an explicit error case (nested replies rejected), and the notification side effect of mentions. It also closes with the return shape ('Returns the new comment').

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?

Front-loads the core action, then the reply constraint, permission, limit, and mention syntax in a tight sequence with no filler. The mention guidance duplicates the body property description word-for-word, which is redundancy rather than added 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?

No output schema exists, and the description compensates by stating what is returned. Together with permissions, size limit, nesting rules, and mention mechanics, an agent has everything needed to call this correctly on the first attempt.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: parentCommentId carries the one-level nesting constraint and the correct fallback (reply to the top-level comment instead). The mention token format is restated almost verbatim from the body property, so there is little net-new parameter information beyond the reply rule.

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 (post a comment) plus the two supported targets (task or project) and the reply variant. An agent can distinguish it from edit_comment, delete_comment, and list_comments without opening any schema.

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

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

Gives concrete preconditions: any team role is permitted, nesting is capped at one level ('a reply to a reply is rejected'), and a 10,000-character limit applies. It also routes the agent to list_users to resolve mention ids. It stops short of naming sibling alternatives (e.g., edit_comment vs. posting a new one) explicitly.

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, non-idempotent mutation. The description adds useful behavioral context beyond that: permissions required, inclusive start-to-end semantics, and that the whole calendar is returned. It does not explain duplicate handling, but the main mutation behavior is well covered.

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

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

Three short sentences, front-loaded with the core action and mode selection, followed by permissions and return behavior. There is no wasted language.

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 four-parameter mutation without an output schema, the description covers the essential context: who can call it, how holiday versus personal leave is selected, inclusive date behavior, and that the full calendar is returned. Minor edge cases like duplicate entries are unspecified but not critical.

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 parameters are already documented in detail. The description reinforces the userId distinction and inclusive date range but adds little beyond what the schema already states.

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: adding a holiday for everyone or a personal leave for one user. It clearly distinguishes the two modes via omission or inclusion of userId, so an agent can tell what the tool does without opening the schema.

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

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

It gives clear usage conditions: omit userId for a company-wide holiday, include userId for one person's leave, and notes the required Administrator or ProjectManager role. It lacks explicit exclusions or reference to the sibling remove_day_off, but the context is still 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 declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, but the description adds substantive behavior the annotations cannot: the concrete side effects (project creation for plan-generator, per-task moves for schedule-doctor), the 402 project-cap failure, and the all-or-nothing re-check that yields a 409 with nothing written when tasks changed. That is exactly the extra context the annotations leave open.

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 state requirement and permissions come first, side effects second, failure semantics third, and the safety warning last as a capped emphatic sentence. Every clause carries distinct information (per-agent behavior, 402, 409, stale, re-run) with no repetition.

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

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

For a destructive, non-read-only mutation with no output schema, the description covers authorization, state precondition, side effects, credit/cap failure, and the stale-conflict outcome, which is everything an agent needs to call it correctly or correctly decline to call it.

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

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

There is a single parameter with 100% schema description coverage, so the schema already carries the meaning of 'id'. The description adds only the implicit constraint that the id must reference a run in state 'proposed', not a broader explanation of the parameter or its acceptable values. Baseline 3 applies when the schema does the heavy lifting.

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 ('Apply') and resource ('a run in state "proposed"') and then differentiates behavior by agent type: plan-generator creates the project, schedule-doctor moves every task in the re-plan. That is enough for an agent to tell it apart from sibling run tools such as reject_agent_run, get_agent_run, or run_agent.

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 precondition (the run must be in 'proposed'), an authorization constraint (Administrator/ProjectManager only), an explicit when-not (do not call before the user has seen the proposal and approved), and a recovery route when the run goes stale ('run the agent again'). This is close to a complete decision 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 flag destructiveHint=true and idempotentHint=true; the description adds substantive context beyond them: the recomputation-at-call-time semantics, that the response reports what actually moved, and the required Administrator/ProjectManager role. No contradictions with the destructive/idempotent hints.

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 the "CONSEQUENTIAL" risk flag and the action front-loaded before the workflow advice. No redundant restatement of the title or schema.

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

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

For a one-parameter mutation with no output schema, the description covers what changes, freshness of computation, return semantics, permission requirements, and the safety workflow. Nothing an agent needs to call it 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?

Single parameter with 100% schema description coverage, so the schema already carries the parameter meaning. The description scopes the operation to a project but adds no format, range, or validation detail 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?

States a specific verb and resource ("reschedule a project — move its tasks' dates") plus the constraint it honors (dependencies and working calendar). The parenthetical "not taken from an earlier preview" separates it from preview_auto_schedule without needing 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?

Gives an explicit workflow precondition ("Preview and confirm with the user first") and contrasts with a stale preview, which steers the agent toward preview_auto_schedule first. It stops short of naming that sibling tool directly, so the routing is clear but slightly inferential.

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 flag destructiveHint=true and readOnlyHint=false, so the safety profile is known; the description still adds real value by disclosing that the result is recomputed at call time, that it returns what actually moved, and that Admin/PM permission is required. It does not state whether prior levelling results are reversible or how many tasks may be touched.

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?

Front-loads the consequence warning, then scope, behavior, permission, and the safety instruction in four compact clauses. No sentence is filler.

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

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

No output schema, but the description tells the agent the call reports what actually moved. Permissions and the preview-first protocol are covered; the missing piece is the time horizon over which 'over-booked' is judged, which matters for a workspace-wide mutation.

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 single utcOffsetMinutes parameter is fully documented in the schema. The description adds nothing about it and never mentions that levelling is evaluated over a time window, which is the only reason the offset exists — so it neither compensates nor misleads.

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 ('level the workload'), the effect ('move tasks across the whole workspace so nobody is over-booked'), and the scope (whole workspace). It is clearly distinguishable from siblings like preview_levelling or get_workload by being the applying action, though it never names preview_levelling 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 pre-condition ('Preview and confirm with the user first') and the role gate ('Administrator or ProjectManager'). It stops short of naming the sibling tool to use for the preview step, leaving the agent to infer that preview_levelling is the counterpart.

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 flag destructiveHint=true and idempotentHint=true, and the description adds substantial context beyond them: it rewrites the live schedule, discards the scenario as a side effect, touches nothing until applied, and requires Administrator/ProjectManager. The permission requirement and irreversible-data-loss framing are not recoverable from 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?

Front-loaded with the effect and the discard side effect, then the confirmation precondition, then the domain explainer. Every sentence carries information, though the sentence about comparison answers is slightly indirect in its wording ('each answer compares...') and could be tightened.

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 single-parameter destructive mutation with no output schema, the description covers the blast radius (all differing tasks and dates), the side effect (scenario discarded), the permission gate, and the preconditions. Nothing an agent needs in order to decide to call it 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 100% and the single parameter is self-documenting, so the baseline is already high. The description adds real meaning by explaining what a scenario *is* (a private copy of one project's dates), which helps the agent supply the correct id rather than guessing between project and scenario ids.

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 effect: 'Make the plan match the scenario — every differing task takes the scenario's dates — then discard the scenario.' It also defines the domain object ('a scenario is a private copy of one project's dates'), so an agent can distinguish apply_scenario from create_scenario, get_scenario, or delete_scenario without opening the schema.

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

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

Gives a clear gating condition: 'only call it once the user has seen the comparison and said to apply it,' which is exactly the confirmation an agent needs before a destructive write. It does not explicitly name the alternative path (delete_scenario to discard without applying), so it falls short of full when-not/alternatives coverage.

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 idempotentHint=true, so the bar is lower. The description adds a genuine behavioral fact not captured in structured data: the operation requires administrator privileges. It stops short of stating irreversibility or whether re-running is safe beyond the idempotent hint.

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, zero waste, with the action and scope front-loaded ahead of the permission constraint.

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 single-parameter destructive operation with full annotation coverage and no output schema, the description supplies action, scope, and the admin requirement. It could mention whether clearing is recoverable, but nothing critical 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?

Only one parameter and schema coverage is 100%, so the schema already documents 'id' as the project id. The description's 'for tasks in this project' slightly reinforces that the id is project-scoped but adds no format or edge-case detail. 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: 'Remove all baseline snapshots for tasks in this project', which tells an agent exactly what is deleted and at what scope. It does not name the companion tool set_project_baseline, so the sibling differentiation is left implicit.

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?

'Administrator only' gives a real precondition for use, but the description never says when to choose this over set_project_baseline or related baseline tools, nor any when-not conditions. Usage is implied rather than guided.

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 already declare destructive=true and idempotent=true, so the safety profile is structured. The description adds valuable context beyond annotations by stating the Administrator or ProjectManager role requirement and that all parent dependencies are removed in one operation.

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

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

The description is a single focused sentence with the action and scope front-loaded, followed by useful usage examples and the permission requirement. There is no unnecessary text.

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 destructive mutation whose annotations already cover safety and idempotency, the description provides the essential operational context: what is removed, why it may be used, and the required role.

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

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

There is one required parameter and schema description coverage is 100%, so the schema already explains childTaskId fully. The description reinforces that this is the child task whose parent links are removed, but adds no syntax or edge-case detail 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 and resource: remove all parent dependencies from one child task. The 'ALL ... at once' wording distinguishes it from single-link removal, but it does not explicitly name or contrast with a sibling such as delete_task_dependency.

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

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

It gives clear usage contexts: before re-linking, or when a task cannot be deleted because links remain. It also states the required role, but it does not explicitly say when not to use it or name the closest alternative.

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 this as a non-read-only, non-destructive, non-idempotent write, and the description adds genuinely new context: the required caller role and the cross-entity workspace constraint. It does not say what happens when an assignment already exists for that task/user pair, which matters given idempotentHint=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?

Three short sentences, front-loaded with the core action, followed by permission and scope constraints. 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?

With no output schema, full schema coverage, and annotations covering safety and idempotency, the description supplies the missing operational context (permissions, workspace scoping). The main gap is duplicate-assignment behavior and whether a success payload is returned.

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 all three parameters are already documented, including the role label and the hint to resolve userId via list_users. The description adds only the workspace-membership precondition, which is validation context rather than parameter semantics.

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

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

States a specific verb and resource: assigning a user to a task, with the optional role label clarified via an example. It doesn't distinguish itself from update_assignment or delete_assignment, so an agent must infer the create-vs-modify split from the name alone.

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

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

Gives explicit preconditions: an Administrator or ProjectManager role is required and both the task and user must belong to the active workspace. It stops short of naming alternatives such as update_assignment for changing an existing assignment's role.

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 only say the tool is a non-destructive, non-idempotent write. The description adds the crucial fact that no email is sent and the draft must be delivered by the caller, plus seat-cap accounting for pending invitations and the plan-limit error surface. A Guest's read-only scope is also disclosed, which no annotation conveys.

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?

Front-loads the action and the most dangerous misunderstanding (no email is sent) before role and email details. Dense but nearly every clause is load-bearing; the all-caps emphasis and repeated 'required' phrasing cost some tightness.

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 correctly describes the return payload (link, subject, plaintext, HTML) and the error case (plan-limit message). Combined with the seat-cap and role semantics, an agent has everything needed to call this correctly and handle 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 coverage is 100%, so the baseline is 3, but the description goes further by explaining that invitedEmail is the only address that can accept (and becomes the draft's To) and by characterizing what the Guest role actually grants. invitedName and personalNote are left to the schema, which is fine given full 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?

Opens with a specific verb and resource ('Create a workspace invitation') and immediately states what is returned (invite link plus a ready-to-send email draft with subject, plaintext, and HTML). This clearly separates it from list_invitations, revoke_invitation, and create_share_link.

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

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

Gives concrete preconditions: administrator only, invitedEmail required and must be obtained from the user rather than guessed, and role constrained to four values. It also explains the Guest role's downstream consequence and the seat-cap behavior on Free plans. It doesn't name a sibling alternative (e.g., revoke_invitation to cancel), which keeps it below a 5.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the mutation/non-idempotent profile is covered. The description adds genuinely new behavioral context: the required role and the plan-limit failure mode with its returned message. It stops short of a 5 by not saying what a successful call returns or whether duplicate names are allowed.

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: purpose first, then the authorization prerequisite, then the quota failure mode. Every sentence carries an actionable fact an agent would otherwise have to discover at runtime.

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 creation tool with no output schema, the description covers the essentials an agent needs to attempt the call safely: scope, role requirement, and quota error behavior. It is only slightly short of complete because the return value (e.g., the new project identifier) is undocumented.

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 `name` and the optional `description` are already documented in the schema. The description adds no format, length, or uniqueness constraints on the name, so the 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 ("Create a project") plus the scope ("in the active workspace"), which is enough for an agent to distinguish it from delete_project or update_project. It doesn't explicitly contrast with the closest sibling create_project_from_template, 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?

The description gives a strong precondition (Administrator or ProjectManager role) and a hard constraint (free-plan cap of 3 projects), which informs when the call will succeed. However, it never names alternatives such as create_project_from_template or explains when to prefer a template-based creation, so usage routing 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 cover the safety profile (readOnly=false, destructive=false, idempotent=false); the description adds genuinely new context beyond them: the operation is atomic ('All or nothing'), requires Administrator or ProjectManager, and counts toward the Free plan's 3-project cap. It also notes the return value, which no output schema supplies.

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

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

Three short sentences, front-loaded with what gets created and how dates are handled, then constraints, then the return value and next step. Every clause carries distinct information; nothing is repeated from the schema or title.

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 non-destructive mutation with full schema coverage and no output schema, the description supplies the missing pieces an agent needs: atomicity, permission requirement, quota impact, and what the call returns. It stops short of describing failure modes (e.g. what a quota-exceeded or permission error looks like), which is the only remaining gap.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema does not: startDate acts as the anchor that all template dates are shifted forward from, and templateId links to list_templates. Optional fields such as lang and description are left to the schema, which is acceptable at full 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?

States a specific verb+resource (create a project from a template) and immediately scopes what that means: the whole task breakdown, milestones and dependencies, dated forward from startDate. This distinguishes it clearly from create_project and save_project_as_template in the sibling list.

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

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

Gives the preceding step (templateId comes from list_templates) and the follow-up step (read its tasks with list_tasks_by_project). It does not explicitly contrast with the sibling create_project for empty projects, so the agent must infer that split, but the workflow framing is otherwise 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 only say it's a non-destructive, non-idempotent write. The description goes well beyond that: role requirements, plan gating with the specific error the agent will see, and the conditional field rules (risk needs both probability and impact, issue keeps only impact, others neither) plus the derived score formula. Those are exactly the behavioral details structured fields don't carry.

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 dense sentences, front-loaded with the action, then permissions, then field rules, then plan gating. Every clause carries information; nothing is padded or restated from the title.

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 10-parameter mutation with no output schema, it covers permissions, plan limits, enum values, and the tricky conditional fields well. It leaves ownerId, response, and description unexplained, and since there is no output schema it never tells the agent what a successful call returns (e.g. the created item and its score).

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 would be 3, but the description adds genuine semantics the schema lacks: the cross-field dependency between kind and probability/impact, the 'others neither' exclusion, and the score = probability × impact derivation. The kind/status enums and dueDate format are also restated in prose for quick scanning.

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: 'Add a line to a project's RAID register.' That is unambiguous and clearly distinct from update_raid_item / delete_raid_item by verb alone. It stops short of explicitly naming those siblings as alternatives, so it lands at 4 rather than 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?

It gives concrete preconditions: requires Administrator or ProjectManager role, and is Pro plan only, with the exact failure mode on Free ('a plan-limit message'). That is strong 'when this will work' guidance. It doesn't route to alternatives (e.g. list_raid_items to check existing entries, update_raid_item to change one), so not 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?

Goes far past the annotations: discloses the per-project scenario cap (422 on overflow), the isolation guarantee (changes invisible until apply_scenario), and the authorization requirement. It also describes what the returned comparison contains. These are exactly the non-obvious traits an agent needs, and nothing contradicts readOnlyHint=false / destructiveHint=false / idempotentHint=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?

Four tight sentences, each carrying distinct information: identity, limit, isolation model, and authorization. The sandbox constraint is front-loaded so an agent knows the risk profile before considering parameters.

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 compensates by describing what each call returns in the comparison (differing tasks with old and new dates, both project end dates). Between that, the permissions note, and the capacity limit, an agent can call this correctly with realistic expectations.

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

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

Schema coverage is 100% with only two required params (name, projectId), both already documented in the schema including a naming example. The description adds the conceptual meaning of a project-scoped scenario but no syntax, constraints, or naming rules beyond the schema. Baseline 3 applies.

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

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

States a specific verb+resource ('Create a scenario for a project') and then defines the resource itself — a private copy of one project's dates that starts identical to the plan. This distinguishes it clearly from apply_scenario (which commits changes) and from list_scenarios/get_scenario.

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 frames the tool as a what-if sandbox whose changes 'touch nothing until apply_scenario', effectively naming the follow-up tool and the condition for switching to it. Also gates the call with 'Administrator/ProjectManager only'. It doesn't discuss delete_scenario or when to prefer working directly on the plan, but the core when/when-not is present.

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 disclosing the real-world consequence (anyone with the URL can view the plan unauthenticated), the permission and plan gating, and the return-value behavior on repeat calls. One tension worth noting: 'the same link comes back' reads as effectively idempotent, while idempotentHint=false claims otherwise — not a safety-critical contradiction (destructiveHint=false is consistent), but the agent may be mildly confused about repeat-call effects.

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

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

Front-loads the CONSEQUENTIAL warning, then packs exposure, permissions, plan tier, confirmation, and repeat-call behavior into three short sentences. No filler; every clause carries decision-relevant 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 one-parameter, no-output-schema tool, the description covers everything an agent needs: what it exposes, who may call it, the plan requirement, the user-confirmation gate, and what the call returns when already shared.

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 a single required projectId, so the schema already carries the parameter's meaning. The description only implies the project scope ('a project's plan') and adds no format or lookup guidance, 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 ('turn on a public read-only link to a project's plan') and makes the scope explicit — public, read-only, anyone with the URL. This clearly distinguishes it from the get_share_link and revoke_share_link siblings without needing to name them.

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

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

Gives clear preconditions and exclusions: Administrator or ProjectManager role, Pro plan only, and an explicit 'Confirm with the user before calling' instruction. It does not explicitly route to siblings (e.g. 'use get_share_link to check whether one already exists'), which keeps it short of 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?

Goes far beyond the annotations: discloses role gating (Administrator/ProjectManager), specific error codes (400 for undefined status label, 422 for missing/inverted dates and for writing computed fields on a summary task), side effects (milestone forces endDate=startDate and collapses an existing range; duration 0; progress 0/100), and derived read-only fields (wbscode, issummary). This is the kind of non-obvious consequence disclosure annotations cannot carry.

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?

Purpose and permissions are front-loaded and the acronym headings help, but the block is ~450 words and repeats the entire status-per-workspace and milestone explanations that already live in the input schema. The WBS/summary-task section is genuinely new information; the duplicated sections are not earning their space twice.

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 14-parameter creation tool with no output schema, this covers everything an agent needs: validation rules, permission gates, cross-tool prerequisites, hidden side effects, and the fact that derived fields will be populated on return. Nothing material is left to inference.

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 does add real meaning the schema lacks — isMilestone's date coercion, wbsParentId being nesting rather than a scheduling dependency, assignedTo needing workspace membership, and Days durations being server-derived — but the status paragraph is largely reproduced verbatim in the schema's own status field, diluting the marginal 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?

Opens with a specific verb+resource ('Create a task in a project') and immediately scopes it with role requirements. It also names the sibling boundaries explicitly (update_task for combined status+percentComplete, create_task_dependency for predecessors), so an agent can distinguish it from adjacent tools without opening 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?

Strong conditional routing: call list_task_statuses before setting a status, use list_users to resolve assignedTo, use create_task_dependency for predecessors rather than wbsParentId. It doesn't enumerate when-not-to-use create_task (e.g., templates, recurring tasks), but the in-flow guidance is concrete and 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?

Goes well beyond the annotations: discloses the auth requirement, the upsert-like behavior when re-creating an existing pair with a new type, and the exact rejection conditions (self-links, cycles, unknown types, date violations). For a non-idempotent, non-destructive write tool with only hint-level annotations, this is substantial coverage of what an agent needs to predict outcomes.

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?

Front-loaded with the core action, then type semantics, then constraints — no filler sentences. The four-clause type sentence is dense but each clause carries distinct information, so it is efficient rather than bloated.

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

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

With no output schema and only hint annotations, the description fills the meaningful gaps: permissions, validation rejections, type semantics, and update-in-place behavior. It omits side effects on scheduling/recalculation after the link is created, which is the only material gap for a 3-param project-planning mutation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by unpacking the FS/SS/FF/SF semantics and default behavior — valuable because the enum is not enforced in the schema (enums: 0) and the schema only gives one-line glosses.

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 ('Create a parent→child dependency') with the directionality spelled out, which distinguishes it from delete_task_dependency, list_task_dependencies, and clear_task_dependencies without needing to open any schema.

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

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

Implies usage clearly (create a dependency between two tasks) and adds a prerequisite gate ('Requires Administrator or ProjectManager role') plus the re-create semantics. It never explicitly names an alternative sibling or a when-not-to-use, so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is largely covered. The description adds useful auth context with "Administrator only," but does not say whether the deletion is permanent or soft, whether related data is affected, or what happens if the id is missing.

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

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

Two short sentences, front-loaded with the core action and followed by the permission constraint. There is no filler or repetition.

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

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

For a simple one-parameter destructive tool whose annotations already cover destructiveness and idempotency, the definition is minimally viable. However, it lacks important context for a delete operation, such as permanence, cascading effects, or behavior when the assignment does not exist.

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

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

There is one parameter and schema description coverage is 100%, so the schema already defines `id` as an integer assignment id. The description only restates "by id" and adds no syntax, format, or lookup semantics beyond the schema.

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

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

States a specific verb and resource: "Delete an assignment by id." This is clear enough to distinguish deletion from siblings like update_assignment, get_assignment, and list_assignments, though the description itself does not name or differentiate any 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?

The only usage condition given is "Administrator only." It does not explain when to choose this tool versus update_assignment or other assignment-management tools, nor does it state any exclusions or prerequisites beyond the admin permission.

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, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds value annotations do not: the permanent erasure of text and the authorization model (self vs Administrator), which an agent needs before calling.

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

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

Two tight sentences with the action and effect front-loaded, followed by the permission rule. Every clause earns its place and nothing is repeated from 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?

For a one-parameter delete with annotations covering destructiveness and idempotency, the description supplies the key missing context: irreversibility and who may invoke it. It does not mention failure modes (e.g., deleting someone else's comment as a non-admin) or effects on threaded replies, which keeps it just short of 5.

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 'id' parameter, so the schema already documents it fully. The description does not add format or constraints beyond the schema, making 3 the correct baseline.

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 ('Delete a comment') and immediately clarifies the effect ('its text is erased for good'). It is clearly distinguishable from edit_comment and list_comments without opening the schema.

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

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

The description gives the permission condition (author may delete their own, Administrator anyone's), which tells the agent when the call is allowed. However, it never contrasts this with edit_comment or other alternatives, and gives no explicit when-not guidance.

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

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

Annotations already declare destructiveHint and idempotentHint, but the description adds context the annotations cannot express: the cascade scope (tasks, assignments, status history), the administrator permission requirement, and the absence of any undo. These are exactly the facts an agent needs to decide whether calling is safe.

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 the most alarming fact (DESTRUCTIVE, cascade) front-loaded, followed by the access constraint and irreversibility. Every clause carries decision-relevant information with nothing repeated.

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 one parameter, no output schema, and annotations already covering the safety profile, the description covers what is destroyed, who may do it, and that it is irreversible. It stops just short of saying whether a trashed project can still be recovered via list_trash or what happens to dependent entities outside the project.

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 required 'id' parameter, so the schema already documents the input fully. The description adds no format, range, or lookup guidance beyond that, which is the baseline case for a fully documented single 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 verb and resource ('permanently delete a project') and immediately defines scope with 'ALL of its tasks, assignments, and status history (cascade)', which distinguishes it from the sibling delete_task and purge_task. An agent knows exactly what this tool removes without opening the schema.

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

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

Usage is only implied through the 'Administrator only' prerequisite and the 'no undo' warning. It never says when to choose this over related tools (delete_task, clear_project_baseline, or any trash/restore path), so an agent must infer the decision boundary.

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, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: required roles, plan restriction, and the plan-limit 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 definition is three short sentences that front-load the action and then state authorization and plan constraints. Every sentence adds operational value 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 simple one-parameter delete tool, the description plus annotations cover the key operational facts: destructive action, idempotency, required role, and plan restriction. Return behavior or not-found handling is not described, but no output schema exists to carry that 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% and the single parameter 'id' is documented as 'RAID line id.' The description does not add syntax or format detail beyond the schema, 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?

The description states a specific verb and resource: 'Remove a line from the RAID register.' That clearly distinguishes deletion from siblings like update_raid_item, create_raid_item, and list_raid_items, though it does not explicitly name alternatives.

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

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

It gives clear usage constraints: the caller must be an Administrator or ProjectManager and the workspace must be on a Pro plan, with a note about Free workspace behavior. It does not explicitly discuss when to choose deletion versus updating, but the access and plan exclusions provide useful 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 declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the underlying plan is unaffected and the operation requires Administrator/ProjectManager permissions. The trailing sentence about "each answer compares the scenario with the plan" is irrelevant to a delete and muddies the behavioral picture slightly.

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 opening and the "plan is untouched" clause are well front-loaded, but the final sentence describing how "each answer compares the scenario with the plan... both project end dates" is leftover from a read tool and does not earn its place in a delete definition. It wastes space and risks confusing the agent about the return value.

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

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

The scope, permission requirement, and non-propagation behavior are covered, which is good for a destructive tool with no output schema. However, the stray sentence implying a comparison result is returned conflicts with the fact that no output schema exists, leaving the agent uncertain about what deletion returns.

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 one parameter at 100% schema description coverage, the schema already explains "id". The description adds nothing specific about the id (e.g., where to obtain it), so the baseline 4 applies rather than a higher 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?

"Throw a scenario away" is a concrete verb+resource, and the description immediately clarifies what a scenario is ("a private copy of one project's dates") and distinguishes it from the plan and from apply_scenario. An agent can tell this apart from siblings like apply_scenario or delete_project without opening a schema.

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

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

It states the key context: the plan is untouched and changes only matter via apply_scenario, implying this is for discarding an experimental scenario. It does not explicitly say when not to use it (e.g., versus apply_scenario to commit changes), so it stops 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 destructiveHint=true and idempotentHint=true, but the description adds crucial behavior beyond them: the task moves to Trash rather than being erased, remains restorable for 30 days, requires an Administrator or Project Manager, fails on child/dependant tasks, and explains the last-child summary-task side effect.

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 definition is dense and front-loaded, with most sentences carrying real behavioral constraints. There is minor redundancy in the standalone 'Administrator or Project Manager' sentence and the first sentence is long, but 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 destructive single-parameter tool with no output schema, the description covers retention period, permissions, recovery path, conflict rules, and summary-task side effects. Nothing essential for correct invocation 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?

There is only one parameter, id, and schema description coverage is 100%, so the schema already documents it as 'Task id'. The description does not add format or selection guidance beyond that, 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 ('Delete a task') and immediately scopes it as a soft delete into Trash with a 30-day restore window. By naming restore_task and list_trash, it distinguishes this from restore and permanent-deletion siblings such as purge_task.

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

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

Gives explicit recovery context via restore_task and list_trash and states the key when-not condition: conflict when the task has WBS children or dependants, requiring re-parenting or deletion first. It stops short of explicitly routing to purge_task for permanent deletion.

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, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new operational context by naming the required role (Administrator or ProjectManager), which is not derivable from any structured field. It stops short of explaining side effects such as whether dependent tasks are rescheduled.

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, zero filler. The action and scope come first, with the access precondition second where a blocking constraint belongs.

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 destructive delete with full annotation coverage and no output schema, the description covers purpose, scope and authorization. The only meaningful gap is downstream effect (dependency removal impact on scheduling), which an agent might want before invoking a destructive tool.

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

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

Schema coverage is 100% for the single parameter, so the schema already defines 'id' as the Dependency id. The description's 'by its id' restates that without adding format, source, or lookup guidance, 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 (delete a task dependency) plus the lookup key (id), and the word 'single' implicitly contrasts with the bulk sibling clear_task_dependencies. It does not name any sibling explicitly, so an agent must infer the boundary itself.

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

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

No explicit when-to-use or when-not-to-use guidance. The qualifier 'single' hints that bulk removal is handled by a different tool (clear_task_dependencies), but the agent must infer that routing rather than being told.

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, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: deletion is restricted to the caller's own reminder (no cross-user deletion) and a call with no existing reminder yields not-found rather than a silent success.

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

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

Two sentences, the operation first and the failure mode second; nothing is repeated from the schema or annotations 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 one-parameter destructive tool with full annotation coverage and no output schema, the description covers the essential behaviors: ownership scope and the not-found outcome. What remains unsaid (whether other users' reminders on the same task are untouched, whether task existence is validated first) is minor.

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

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

Schema description coverage is 100% and the single taskId parameter is fully documented in the schema. The description adds no format, range, or ownership hints about taskId, 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 (Remove) and a precisely scoped resource (the caller's own reminder on a task), which separates it from delete_task and set_task_reminder. It never names a sibling explicitly, so differentiation is achieved through resource precision rather than explicit routing.

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 caller's own reminder" implies the ownership precondition for use, but the description gives no explicit when-to-use/when-not-to-use guidance and points to no alternative (e.g. list_my_reminders to check first, or set_task_reminder to overwrite instead).

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 idempotentHint=true, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: who is authorized to delete and the plan-limit error behavior in Free workspaces.

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

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

The description is three short sentences, front-loaded with the core action, followed by permission rules and plan constraints. Every sentence adds useful information with no waste.

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

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

For a simple one-parameter delete tool with rich annotations, the description covers the essential action, authorization model, and plan gating. No output schema exists, and the annotations already cover destructiveness 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?

There is one parameter and schema coverage is 100%, so the schema already documents the only input. The description does not add syntax or format details about the time entry id beyond what the schema provides, making 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?

The description uses a specific verb and resource: 'Delete a time entry.' It is clearly distinct from sibling tools like update_time_entry, log_time, and list_time_entries by operation type, though it does not explicitly name an alternative 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?

It provides clear usage context: owner versus Administrator permissions and the Pro-plan requirement, including the Free-workspace failure mode. It does not explicitly route between this and alternatives such as update_time_entry, but the delete operation 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?

Beyond the annotations, it discloses the ownership restriction, that the entire body is replaced, that mention tokens trigger notifications, and that the updated comment is returned. These are material behavioral details not captured by readOnlyHint, idempotentHint, or destructiveHint.

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 front-loaded with the action and ownership constraint, then moves efficiently through replacement behavior, mention syntax, and return value. The example earns its place by illustrating a non-obvious token 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 two-parameter mutation with rich annotations, the description covers ownership, replacement semantics, mention syntax, and return behavior. Nothing important for correct invocation 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 100%, but the description adds essential meaning for the body parameter: the exact @[Display Name](userId) mention syntax, the requirement for an integer id, and the consequence that plain names notify nobody. That is substantial parameter semantics 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 and resource: "Rewrite one of the caller's OWN comments." It distinguishes this from add_comment and delete_comment by making clear it replaces an existing comment body, and it adds the ownership constraint.

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 clearly says when editing is allowed (only the caller's own comments) and explains the mention workflow needed when editing. It does not explicitly name add_comment or delete_comment as alternatives, but the operation boundary is otherwise 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 cover read-only, idempotent, non-destructive, so the description's job is to add operational context — and it does: newest-first ordering, cursor-based pagination semantics, and a Free-workspace 90-day retention limit that materially changes what results the agent can expect. It does not describe rate limits or response envelope details, but for a read-only list that is a minor gap.

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

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

Four sentences, each carrying distinct information: what it returns, how to filter, what an event looks like, how to paginate, and the retention constraint. The core identity is front-loaded and nothing is repeated from the schema verbatim.

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 compensates by describing the event shape (eventKind values plus a raw payload) and the cursor/nextBefore paging contract, and it flags the 90-day data window. An agent has everything needed to call and page through it correctly.

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

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

Schema coverage is 100%, so baseline is 3; the description earns above baseline by explaining filter combination logic (entityType must pair with entityId; projectId and actorId are independent scopes) and by spelling out pagination flow, which the terse schema labels alone don't convey.

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 ("Read the workspace's activity feed") and disambiguates it from the rest of the catalog by defining it as the audit trail of who did what, ordered newest first. No sibling (get_task_status_history, list_comments) does the same thing, so an agent can select it confidently.

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 tells the agent how to narrow the feed: one entity via entityType+entityId, a whole project via projectId, or a person via actorId, plus the cursor rule (pass reply's nextBefore as before). It gives clear usage context but never names a sibling as a mutually exclusive alternative, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: it enumerates the lifecycle states (queued through failed), lists returned fields including credits charged and any error, and frames the tool as a polling mechanism, though it omits details like behavior when the run 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?

The description is two sentences with zero waste: the first front-loads the core action and enumerates return contents efficiently; the second gives a terse, actionable polling instruction. Every element 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 and only one fully documented parameter, the description compensates by thoroughly enumerating the returned fields and lifecycle states. It also clarifies the polling usage pattern, making it complete enough for an agent to call the tool correctly without additional documentation.

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

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

The input schema has 100% description coverage for its single parameter ('id': 'Run id'), so the schema already explains the parameter fully. The description reinforces that this is a run identifier by context but adds no syntax, format, or meaning beyond what the schema provides, making 3 the appropriate baseline.

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 ('Read one agent run') and enumerates exactly what is returned: state, summary, plan, model, tokens, credits, and error. It distinguishes itself from the sibling list_agent_runs by emphasizing 'one' run, and from run_agent by its read-only polling role.

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

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

It explicitly states 'Poll this after run_agent', giving a clear primary use case. However, it does not mention alternatives like list_agent_runs for enumerating multiple runs or clarify whether it can be used outside the polling workflow, leaving a small gap in explicit when-not guidance.

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

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

Annotations already establish readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful behavior the annotations cannot: 'Each agent run holds credits first and settles to what the model actually used', which explains why balances may look momentarily reserved rather than settled.

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?

Front-loaded with the core noun phrase ('The active workspace's AI credit balance') followed by a compact enumeration and one clarifying sentence about settlement. The middle enumeration is a long comma run-on, but every item listed is information the agent would otherwise lack.

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 must carry the return shape, and it does: available credits, monthly allowance, trial credits, purchased packs, reset timing, purchasable packs, and recent ledger lines. What it lacks is any indication of units, magnitude, or how much ledger history is returned.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The implicit 'active workspace' scoping is the only parameter-like concept and is stated in the description.

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

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

States a specific verb and resource ('get ... AI credit balance') scoped to 'the active workspace', then enumerates the components returned. It does not distinguish itself from the potentially overlapping sibling get_entitlements, 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 only implied by the content described — there is no explicit 'use this when…' clause, no exclusion, and no pointer to an alternative such as get_entitlements. For a zero-parameter read tool the implied use is fairly obvious, but nothing steers the agent between competing lookups.

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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is clear. The description adds only the singular-fetch nuance ('single assignment'), without additional details such as error behavior or return shape.

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

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

The description is a single, front-loaded sentence with no wasted words. It communicates the core action and lookup key immediately.

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

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

For a simple single-record getter with rich annotations and complete parameter schema coverage, the description is nearly sufficient. It does not describe return fields or not-found behavior, but those gaps are minor given the tool's simplicity and the absence of an output schema.

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

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

Schema description coverage is 100%, and the sole parameter 'id' is documented as 'Assignment id.' The description adds no further meaning beyond what the schema already provides, 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?

The description names a specific verb and resource: 'Get a single assignment by its id.' That is clear and distinguishes a single-record fetch from list-style siblings such as list_assignments and list_assignments_by_task, though it does not explicitly name those alternatives.

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 its id' implies the tool should be used when an assignment id is already known, but the description does not explicitly state when to use this versus list_assignments or other retrieval tools. Usage guidance is therefore implied rather than spelled out.

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 readOnly/idempotent annotations by disclosing the baseline-vs-no-baseline behavior, authorization requirements, plan gating with the actual failure mode, currency scoping, and how utcOffsetMinutes shifts the "to date" calculation. This is exactly the operational context annotations cannot carry.

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?

Front-loaded with what the tool returns, then constraints in descending importance (baseline, role, plan). The acronym list is dense but every term earns its place since there is no output schema to document return fields.

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, describing the returned metrics is essential and it does so completely, including how to interpret SPI/CPI. Permissions, plan limits, baseline behavior, and timezone handling are all covered — nothing an agent needs to call this 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 coverage is 100%, so both parameters are already documented. The description reinforces the meaning of "to date" via PV but adds little syntax or behavior detail beyond what the schema provides, 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+resource (earned-value figures for a project) and immediately enumerates the returned metrics with acronym expansions, so an agent knows exactly what it gets back. It is clearly distinguishable from siblings like get_project_costs or get_progress_trend.

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

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

Gives concrete usage context: requires Administrator or ProjectManager role, Pro plan only, and warns that a Free workspace returns a plan-limit message. However it never names alternatives (e.g. get_project_costs) or states when not to use this tool, so no explicit 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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety is covered and the description's job is narrower. It adds real value by disclosing the returned content and the feature-gating semantics (which capabilities are Pro), though it says nothing about auth requirements, workspace scoping behaviour for non-active workspaces, or error cases on a free plan.

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 return payload and followed by the Pro-feature note that explains why the plan data matters. No filler, no restatement of the title.

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 input parameters, no output schema and full annotation coverage, the description carries the remaining burden by enumerating the returned fields and the plan gating rule. Nothing an agent needs in order to call it correctly or interpret the result is missing.

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

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

The tool takes zero parameters and the schema is empty, so there is nothing to disambiguate; baseline 4 applies. The description correctly implies the workspace is implicit ('the active workspace's'), which is the one semantic point worth flagging for a parameterless tool.

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 plus resource ('Return the active workspace's plan and usage') followed by an enumeration of exactly what comes back: plan tier, subscription status, seat/project limits vs counts, and trial/period end dates. That enumeration makes it unmistakable against neighbours like get_ai_credits or whoami, which return different slices of account data.

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 it should call this to check whether Pro-gated features (time tracking, costs, RAID, share links, webhooks) are available. There is no explicit 'use this when...' or 'do not use this for...' clause, and no named alternative such as get_ai_credits for credit-specific questions.

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 read-only, idempotent, non-destructive, closed-world profile, so the bar is lower. The description still adds valuable behavior: the team-role access restriction and the SPI interpretation rule (SPI < 1 = behind plan), which an agent could not infer from 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?

It is front-loaded with the burn-up concept and packs the return contents, the diagnostic question, and the access restriction into three tight sentences with no filler. Parentheticals are used efficiently to cover project-vs-workspace scope and SPI direction.

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, but the description explains the returned content well enough (scope vs done by day, planned vs earned percent, SPI). Safety is covered by annotations and the access restriction is stated, though the exact response shape and row granularity are left implicit.

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, including utcOffsetMinutes, are already fully documented. The description reinforces that days means a trailing window and that omitting projectId selects the whole workspace, but it adds no syntax or format 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?

The description names a specific artifact (burn-up), the scope (one project or the whole workspace), and the exact metrics returned (scope vs done day by day, planned vs earned percent, SPI). An agent can distinguish this reporting tool from siblings like get_earned_value without opening the schema.

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

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

It gives clear usage context through the framing question ("are we on track / speeding up / slipping?") and a role restriction ("Team roles only"). It does not explicitly name an alternative tool or when-not to use this one, so it falls 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, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered structurally. The description adds useful scope by noting retrieval is from the "active workspace," but does not mention not-found behavior, permissions, or return shape.

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 definition is a single, front-loaded sentence with no wasted wording. It communicates the action, resource, lookup key, and workspace scope efficiently.

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

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

For a simple read-only single-entity lookup with rich annotations and a fully documented parameter schema, the description is largely complete. It could optionally clarify return content or not-found behavior, but those gaps are minor for this tool shape.

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 sole parameter is documented as "Project id" with integer type. The description reinforces that lookup is by id but adds no format, validity, or source details 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 and resource: "Get a single project by id." It implicitly distinguishes this from list_projects by emphasizing a single project, and from update/delete by using "Get," but it does not explicitly name sibling alternatives.

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 guidance on when to use this tool versus alternatives such as list_projects or get_projects_report. The intended use is implied by "single project by id," but no exclusions or alternative-routing guidance are 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?

With readOnlyHint already declaring safety, the description adds substantial context: role-based visibility (a ProjectManager sees hours but not cost), unpriced-time reporting as unpricedMinutes, and a specific plan-limit failure mode for Free workspaces. These are behaviors an agent cannot infer from annotations or schema.

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?

Front-loaded with what is computed, then permissions and edge cases. Dense but each sentence carries distinct information; the parenthetical rate formula is slightly heavy but earns its place by defining actual cost.

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

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

No output schema exists, so the description must convey return content, and it does: budget vs actual vs planned cost, per-person hours, and unpricedMinutes. It does not fully describe the response structure, but it is sufficient for an agent to decide to call it and interpret the key fields.

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

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

Only one parameter with 100% schema description coverage, so the schema already carries the burden. The description adds no syntax or format detail for projectId beyond what the schema states, which is the expected baseline at 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?

States a specific verb+resource and defines the computation precisely: budget vs actual cost (logged time × hourly rates) and planned cost, with hours per person. That distinguishes it from siblings like get_project, get_earned_value and get_resource_usage without needing to open any schema.

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

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

Gives clear preconditions for use: Administrator or ProjectManager role, Pro plan only, and notes what a Free workspace returns. It doesn't explicitly route the agent between this and cost-adjacent siblings (e.g., get_earned_value, get_resource_usage), but the access conditions are concrete and 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added value is the "Team roles only" authorization restriction and the detailed breakdown of what the response contains. With no output schema present, spelling out the returned sections is genuinely useful. It doesn't state whether archived/completed tasks are included, a minor gap.

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

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

Two sentences, front-loaded with the report contents and closing with the use case and access restriction. The content enumeration is dense but each clause conveys a distinct returned section; no filler or repetition.

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

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

With no output schema and no params, the description must carry the return-value burden, and it does so by listing every report section. Combined with the access note, an agent has enough to select and call it. Minor omission: no hint about scope limits (e.g., whether completed/archived projects or date ranges are included).

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing parameter-level for the description to disambiguate, and it correctly spends no words on inputs.

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

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

States a specific verb and resource (a projects report) and enumerates the exact contents: per-project task counts by status, percent complete, dates, overdue counts, next milestone, plus workspace overdue/at-risk tasks and per-person counts. This clearly separates it from siblings like get_progress_trend, get_earned_value, or get_workload, which cover narrower analytics.

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 best single call for 'how are my projects doing?'" gives an explicit usage scenario and positions it as the aggregate alternative to multiple narrower calls. "Team roles only" adds a prerequisite constraint. It stops short of naming specific sibling tools it replaces or when not to use it, keeping it below a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered. The description adds the shape of the result set (one row per member with an overload flag), but says nothing about how capacity is derived, whether all-time or current-period data is returned, or how large workspaces are handled.

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

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

Two tight sentences with no padding. The output content comes first and the interpretive hint ('spotting over-assigned people') is deferred to the end, which is the right ordering.

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

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

With no output schema, the description usefully enumerates the returned fields, which is the key thing an agent needs. The remaining gap is temporal scope — it is unstated whether the summary reflects all current assignments or a period — but nothing else material is missing for a zero-argument 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?

The tool takes no parameters and the schema is empty, so there is nothing for the description to disambiguate. Baseline for a zero-parameter tool applies; no credit is lost, but the description also has no chance to clarify a scope argument (e.g. a date range) that would have been useful.

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-plus-resource: returns a resource-allocation summary per workspace member, and names the three concrete outputs (allocated days, effective daily capacity, overloaded flag). It is clear what the tool produces, though it never distinguishes itself from the similarly-scoped get_workload 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?

'Useful for spotting over-assigned people' implies a use case but gives no when-to-use rule, no exclusions, and no routing to alternatives such as get_workload — an agent must infer which of the two workload views to pick.

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 readOnly, idempotent and non-destructive, and the description reinforces them rather than contradicting: changes in the scenario 'touch nothing until apply_scenario'. It adds genuinely new behavioral context by describing the response content (differing tasks, old and new dates, both project end dates) and the role requirement.

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?

Front-loaded with the comparison purpose, but the phrase 'the plan as it stands now' appears twice with near-identical wording, so not every sentence earns its place. The access restriction is buried at the end rather than signaled up front.

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 single-parameter read tool with no output schema, the description covers purpose, side-effect profile, permissions and what the answer contains. An agent could call it correctly; only the source of a valid scenario id and any behavior for a stale/applied scenario are left implicit.

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

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

Only one parameter and schema coverage is 100%, so the 'Scenario id' description already carries the meaning. The body text only implies the id selects a single scenario, adding nothing about format or how to obtain a valid id (e.g. via list_scenarios). Baseline 3 applies when the schema does the work.

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

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

Names a specific verb and resource ('Compare one scenario with the plan as it stands now') and defines what a scenario is (a private copy of one project's dates). The mention of apply_scenario as the commit step distinguishes this read/compare operation from the mutation siblings without the agent needing to open another schema.

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

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

Gives a clear operating context: this is the non-destructive preview, nothing changes until apply_scenario, and it is restricted to Administrator/ProjectManager. It does not explicitly say when to prefer it over list_scenarios or create_scenario, so it falls short of a full when/when-not treatment.

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 safety (readOnlyHint, idempotent, non-destructive), and the description usefully adds the role requirement. It leaves an important behavioral question open: what happens when sharing is off – an error, a null, or an empty result.

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, no filler, with the return behavior front-loaded and the permission constraint second. Nothing in it is redundant.

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 is the only place to learn what comes back – it says 'read-only share link' but not the URL shape or the failure case when sharing is disabled. Adequate for a one-parameter read tool, 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?

With a single parameter at 100% schema coverage, the schema already establishes 'projectId' as an integer project id. The description only reuses the possessive 'a project's', adding no format, scope, or validation meaning beyond the schema.

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

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

States a specific verb and resource ('Return a project's read-only share link') plus the gating condition ('if sharing is on'). It implicitly separates itself from create_share_link and revoke_share_link by being the read side, though it never names those 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?

Gives a precondition ('if sharing is on') and a caller restriction ('Administrator or ProjectManager'), which is real usage context. It does not say when to reach for this versus create_share_link or revoke_share_link, so the agent must infer the alternative.

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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is clear. The description adds only the 'single task' scope and does not describe not-found behavior, permissions, or returned task fields, which is acceptable but minimal given the strong annotations.

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

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

The description is a single short sentence with the resource and lookup key front-loaded. It has no redundant or wasted language.

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 read tool with comprehensive annotations and full schema coverage, the description is sufficient to invoke correctly. The main remaining gap is the absence of return-value detail, but 'Get a single task' reasonably implies a task object.

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

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

Schema description coverage is 100% and the single parameter is documented as 'Task id'. The description reinforces that the id identifies a task but adds no format, validation, or lookup semantics beyond what the schema already provides, 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?

The description uses a specific verb and resource: 'Get a single task by id.' This clearly identifies the operation and distinguishes it from list-style tools, but it does not explicitly differentiate it from nearby siblings such as get_task_status_history, get_task_time, or list_tasks_by_project.

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 id' weakly implies that the tool is appropriate when a task id is known, but there is no explicit when-to-use guidance, no exclusions, and no named alternative such as list_tasks for broader retrieval.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral facts: results are ordered newest-first and include the actor and timestamp per change. It stops short of disclosing volume limits, pagination, or whether all transitions or only status changes are returned.

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

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

A single sentence with no filler; the ordering constraint and the audit-log framing are front-loaded and both earn their 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 must carry return-value information, and it does so only partially — 'who moved it when, newest first' implies actor/timestamp/status fields but not the exact shape, entry count, or pagination. For a simple single-parameter read tool this is adequate but leaves 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?

Only one parameter (taskId) and schema coverage is 100%, so the schema already documents it fully. The description adds no information about the parameter itself — no mention of what happens for an unknown task id or whether the id refers to a top-level task vs subtask. Baseline 3 applies when the schema does the work.

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 (status-change timeline for a task), and adds ordering and content semantics ('newest first', 'audit log of who moved it when'). It is clearly distinguishable from get_task or get_activity by the explicit 'status-change timeline' scoping, though it does not name any sibling directly.

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

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

Usage is implied by the resource name — you call this when you need the history of a task's status transitions — but there is no explicit when-to-use guidance, no mention of how it differs from get_activity, and no prerequisites (e.g., task must exist, permission required).

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 read-only/idempotent/non-destructive profile, and the description goes well beyond them: it discloses that the result set is permission-dependent (all entries for Administrator/ProjectManager, only the caller's own for a Member) and that a Free workspace returns a plan-limit message. Permission-scoped output and plan-gated failure behavior are exactly the non-obvious traits an agent needs before calling.

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 resource and the returned values, then the plan constraint. Every clause carries information — the em-dash enumeration of what is returned and the role split both earn their space; 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?

With no output schema, the description carries the burden of describing return values and it does so (total minutes, effort-derived estimate, entries). It omits finer detail such as whether the estimate is null when effort is unset or whether entries are truncated for large tasks, which keeps it from a 5 for a non-trivial aggregate.

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

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

There is a single required parameter with 100% schema description coverage, so the schema already documents taskId fully. The description adds no format, scope, or edge-case detail about taskId beyond what is in the schema, making 3 the appropriate baseline.

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 ('Time logged on one task') and enumerates the three things returned: total minutes, the estimate from effort, and the entries. An agent can tell this is a per-task time aggregate rather than the raw entry listing of list_time_entries. It does not name any sibling 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?

Gives a hard prerequisite — 'Pro plan only (a Free workspace gets a plan-limit message)' — which is real usage guidance. However, it never says when to reach for this versus get_task, list_time_entries, or get_earned_value, so the choice among alternatives is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds only the scoping detail that the target is a workspace member; it says nothing about missing-id behavior, error results, or visibility restrictions.

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 front-loaded sentence with zero redundancy; the resource, the singular scope, and the lookup key all appear immediately.

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 tool with full schema coverage and complete safety annotations and no output schema, the definition is close to sufficient. The only real gap is what happens on an unknown id, which an agent would benefit from knowing.

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

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

Schema description coverage is 100% and the single parameter is typed as integer, so the baseline is 3. The description restates the id type and meaning but adds no syntax, range, or format guidance beyond the schema.

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

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

States a specific verb and resource ('Get a single workspace member') plus the lookup key ('by their integer user id'), which is unambiguous. It does not explicitly differentiate itself from list_users or whoami, so an agent must infer the distinction from the singular wording.

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: 'single ... by their integer id' tells the agent this is the lookup for when an id is already known, leaving list_users as the alternative. There is no explicit when-to-use/when-not or sibling routing 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 declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds real value beyond them by explaining the calendar's semantics — that durations in days are measured in working days and that scheduling/workload consume this data — which an agent cannot infer from 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?

One dense sentence that front-loads the resource and return contents, followed by the semantic note. Nearly every clause earns its place, though the userId phrasing is both wrong and verbose.

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

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

With no output schema, the description must carry return-value explanation; it names the categories but not their shape or format (e.g., how hours-per-day and days-off are structured). The nonexistent userId parameter is left unresolved, creating a real ambiguity for a zero-argument tool.

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

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

The input schema has zero properties, so the baseline would be 4. However, the description repeatedly references a 'userId' input ('public holidays (no userId)', 'with userId'), which does not exist in the schema — this actively misleads an agent into attempting to pass an argument the tool does not accept.

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 ('Read the workspace's working calendar') and enumerates exactly what it returns: working weekdays, hours per working day, and days off. This clearly separates it from siblings like add_day_off, remove_day_off, and get_workload.

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

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

It gives domain context that implies when the result matters ('Task durations in days count working days only, and scheduling and workload use this calendar'), but never says explicitly when to call this tool or which alternative to pick. No prerequisites or exclusions are 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 this as a safe, read-only, idempotent operation. The description adds useful behavioral context beyond annotations: it starts from the current week, explains the available-hours inputs, and defines over-booking via allocatedHours above capacityHours or overDays > 0. It still does not discuss permissions or error behavior, so a 4 is appropriate.

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, front-loaded with the core purpose, and uses every sentence productively. The reporting scope and over-booking interpretation are presented without unnecessary repetition.

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

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

With no output schema, the description usefully identifies the key returned fields and over-booking logic, and the annotations cover the safety profile. It is largely complete for an agent to call the tool, though it does not fully describe the response shape or all possible returned fields.

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 the schema. The description implies a forward-looking weekly range and user-local week boundaries, but does not add parameter-level syntax or defaults. Baseline 3 applies when the schema does the heavy lifting.

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 resource and scope: weekly workload per person, comparing task hours against available hours from working calendar, capacity and leave. It is specific about the output and what over-booked means. It does not explicitly distinguish itself from similar reporting siblings such as get_resource_usage, so it falls 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?

Usage is implied by the weekly workload reporting context and the scope restriction 'Team roles only.' However, there is no explicit guidance on when to choose this tool versus alternatives like get_resource_usage, and no exclusions beyond the team-role restriction.

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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds non-obvious behavior beyond that: deterministic ordering (newest first) and the direction of paging, which matter for correct iteration. It stops short of disclosing page size or default 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?

A single sentence with the core operation front-loaded, then scope, ordering, and paging guidance in descending priority. 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?

With no output schema, the description carries the burden of describing what a run record contains and what a page returns (size, cursor termination), and it does neither. Ordering and paging direction are covered, so it's adequate but with a clear gap for an agent that must interpret 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 coverage is 100%, so the baseline is 3, but the description adds a genuinely useful recipe not in the schema: `before` should be the smallest id already seen, which pins down the exact paging convention. `projectId` scoping is restated rather than extended, so it's a modest net gain.

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 recent agent runs") plus scope (active workspace, newest first, optional project filter). It is clearly distinguishable from get_agent_run by name and behavior, though the description never explicitly contrasts itself with that or other 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?

Usage is implied rather than stated: the agent can infer this is the browsing/paging entry point for runs, and the pagination instruction gives a concrete procedure. There is no explicit "use get_agent_run when you have an id" routing or any when-not guidance.

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

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

Annotations already establish the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the description earns credit for what it adds: the concrete shape of each returned entry and the side-signal that it also reports whether AI is configured on the server at all. That last clause matters behaviorally — a caller can learn AI is unavailable without a failed run — and is not derivable from any structured field.

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 scope, with the em-dash clause carrying only substantive content. Every clause maps to a distinct piece of returned data, so nothing is filler despite the length.

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

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

With no output schema and no parameters, the description's main obligation is to describe what comes back, and it does so field by field. Minor gap: it does not say whether the list is filtered by the caller's role (only that per-agent runnability is reported) or note any ordering/absence case such as an empty list when AI is unconfigured.

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

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

The tool takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly spends no words on input semantics.

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

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

States a specific verb and resource ("List the AI agents this workspace can run") and then enumerates exactly what each entry conveys: kind, projectId requirement, applyability, credit cost, and role permission. This implicitly separates it from list_agent_runs and get_agent_run, but never names those siblings, so an agent scanning a long sibling list must infer the boundary itself.

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

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

No explicit when-to-use, prerequisites, or alternative is given. The natural workflow (call this before run_agent or apply_agent_run to pick an agent) is only implied by the returned fields, such as 'whether its result can be applied' and 'typical cost in credits'. Usable but left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only the scope hint that the result covers the entire workspace. It says nothing about response size, pagination, or ordering for what could be a large unfiltered list.

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 waste, and the scoping statement is front-loaded ahead of the sibling routing guidance. Each sentence carries distinct, actionable 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 zero-parameter read tool with rich annotations and no output schema, the description covers purpose, scope, and alternative routing — enough to invoke it correctly. The only missing piece is guidance on result volume or pagination for a workspace-wide 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?

The tool takes zero parameters, so there is no parameter semantics for the description to explain. Baseline 4 applies; the description correctly implies no filtering arguments exist.

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 all user↔task assignments") plus an explicit scope ("in the active workspace"). It also names the sibling it is not (list_assignments_by_task), so an agent can distinguish them without opening either schema.

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

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

Explicitly says when to prefer the alternative: "Prefer list_assignments_by_task when you only need one task's assignees." It also states the condition that selects this tool instead — the request spans the entire workspace — leaving nothing to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely new behavior ('Returns 404 if the task is not in the active workspace'), which tells the agent how failure manifests. It doesn't mention ordering or pagination, but for a filtered read that is a minor gap.

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

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

Two short sentences with zero waste. The core operation is front-loaded and the 404 behavior follows as supporting detail.

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

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

For a simple, fully annotated, single-param read tool this is nearly complete: it names the returned entity (the users assigned) and the failure mode. With no output schema, a brief note on ordering or empty-result behavior would be the only addition, which is a small 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?

There is a single parameter (taskId) with 100% schema coverage, so the schema already documents it. The description's phrase 'one task' reinforces that exactly one task id is passed, but adds no format or syntax detail beyond the schema. 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 ('List the users assigned to one task') and adds the scoping qualifier 'server-side filtered', which separates it from the broader list_assignments and from get_assignment. It stops short of naming those siblings explicitly, so differentiation is implied by scope rather than spelled out.

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: call this when you have one task id and want its assignees rather than all assignments. The 404 note hints at a precondition (task must be in the active workspace), but there is no explicit when-to-use/when-not guidance or named alternative.

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/non-destructive annotations, the description adds substantial behavior: ordering is oldest first, replies use parentCommentId, threads are one level deep, deleted comments appear as tombstones only when a live reply exists, and mentions use a specific format. This is exactly the kind of context an agent needs to interpret results correctly.

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 front-loaded with purpose and then packs useful behavioral details about ordering, threading, tombstones, and mentions without wasting space. Every clause contributes to correct invocation or interpretation.

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 tool with full schema coverage and no output schema, the description is largely complete: it explains the main result shape, reply threading, deleted-comment tombstones, and mention syntax. It does not mention pagination or whether all comments are always returned, which would fully close the remaining gap.

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

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

Schema description coverage is 100%, so both entityId and entityType are already documented in the schema. The description reinforces that the thread belongs to a task or project, but adds no syntax or format details beyond what the schema already 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 states a specific verb and resource: 'Read the comment thread on a task or a project.' It also adds ordering ('oldest first'), which clearly distinguishes this list operation from add_comment, edit_comment, and delete_comment 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 gives clear usage context: it is for reading comments attached to either a task or a project. It does not explicitly name alternatives such as add_comment or edit_comment, nor does it state when not to use it, but the intended 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds value beyond that by disclosing the shape of the returned records, including the enumerable type values (text, number, date, checkbox, select, url) and the conditional 'options' field for selects — context an agent cannot get from 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?

A single tight sentence, front-loaded with the verb and resource, then the return fields, then the alternative-tool pointer. Every clause earns its place with no repetition of the title 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?

Because there is no output schema and no parameters, the description must carry the return-shape burden, and it does: it lists the returned attributes and type values. A mention of ordering, workspace scoping requirements, or whether archived fields are included would push this to a 5.

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

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

The tool takes zero parameters, so the schema imposes nothing to explain and the baseline of 4 applies. The description correctly spends its words on output semantics instead of inventing parameter guidance.

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

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

States a specific verb and resource ('List the workspace's custom task fields') and enumerates exactly what is returned: id, name, the type enum, and select options. This makes it immediately distinguishable from the sibling list_custom_field_values, which the description explicitly names as the tool for values.

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 closing sentence, 'Values are read with list_custom_field_values,' gives a clear routing rule: use this tool for field definitions, use the sibling for per-task values. There are no explicit exclusions or preconditions, but in a zero-parameter read tool that is a minor gap.

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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds behavior the annotations can't: the exact row tuple returned and the requirement for a follow-up lookup to make fieldId human-readable. It doesn't mention pagination or result-size limits, which is the remaining gap.

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

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

One sentence plus a short join hint; the output shape and scope are front-loaded and every clause carries information. 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?

With no output schema, the description correctly compensates by declaring the row tuple, and it flags the two-step name resolution. For a workspace-wide list it doesn't say whether results are paginated or bounded, which is the one thing an agent might still need before calling.

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

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

Schema coverage is 100% and the single parameter is documented as optional, so the baseline is met. The description goes further by spelling out the consequence of omitting projectId — you get the whole workspace — which the schema's 'optional' alone does not make explicit.

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 custom-field values) plus the exact output shape — (taskId, fieldId, value) rows — and the scope (one project or whole workspace). It also distinguishes itself from the adjacent list_custom_fields tool by positioning that one as the source of field names, so an agent can pick between them immediately.

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 clear context: use with projectId for a single project, omit it for the whole workspace, and join fieldId against list_custom_fields to resolve names. It doesn't name an explicit exclusion or a conflicting alternative (e.g. reading a single task's fields via get_task), so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description adds genuinely new behavioral context by disclosing the admin-only authorization requirement, which matters for error handling. It says nothing about pagination, result ordering, or result size 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 short sentences with zero waste; the scope and status qualifier come first and the permission constraint follows. Nothing to trim.

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 tool with full annotation coverage, the description supplies the two things annotations can't: workspace scoping and admin gating. The only gap is behavior at scale (pagination/result caps), which is minor given there is no output schema to defer to.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies no inputs are needed to scope the 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?

States a specific verb and resource ('List all invitations') plus the scope ('active workspace') and status filter ('any status'), which distinguishes it from create_invitation and revoke_invitation. It doesn't explicitly name a sibling, but the 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?

'Administrator only' signals a prerequisite, and '(any status)' implies this is the unfiltered enumeration option. However, there is no explicit when-to-use guidance, no mention of how it relates to list_users or list_project_guests, and no note on what to do if the caller lacks admin rights.

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 readOnly/idempotent/closed-world, so safety is covered; the description adds genuinely new behavior: result ordering (newest first), the fields each row carries (kind, event, actorName, readAt), and the null-means-unread convention. Cursor mechanics are described, though rate/limit behavior is left to the schema.

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: scope first, then the row shape, then pagination. No filler, and the most decision-relevant information (what it reads and whose) 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?

There is no output schema, so the description carries the return shape and it does so — row fields, ordering, and the cursor round-trip. Combined with the fully documented schema and read-only annotations, an agent has everything needed to call this once and then page 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%, so a baseline 3 applies, but the description adds meaning the schema lacks: 'pass nextBefore as before' links the page token in the response to the `before` parameter, and 'readAt (null = unread)' ties into unreadOnly. Only `limit` is left entirely to the schema.

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

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

States a specific verb and resource ('Read the caller's own notification inbox') and enumerates the content types it covers (assignments, mentions, comments on their tasks). 'Caller's own' plus 'notification inbox' clearly separates it from list_my_reminders, list_comments and the mark_*_read 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?

Gives clear context — the caller's own inbox only, newest first — and explains how to continue paging. It never names an alternative or an explicit when-not condition (e.g. use mark_all_notifications_read to clear, or unreadOnly instead of paging), so it stops 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, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds value beyond that: it bounds the scope to the caller's own reminders in the active workspace and guarantees a deterministic ordering (soonest first), which is real behavioral context for a read tool.

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

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

Two sentences, no filler. Scope and ordering are front-loaded in the first sentence, and the return fields follow. 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?

There is no output schema, so the description must describe the shape of the result, and it does: task id, title, workspace, and reminder time with an explicit UTC note. Combined with the ordering guarantee, an agent has everything needed to call and interpret this tool.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-param tool applies. The field list in the description describes return values, not inputs, and does not confuse the two.

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 gives a specific verb plus resource ("List the caller's own task reminders") and narrows scope with "in the active workspace, soonest first," which separates it from general lists like list_tasks. It never names a specific sibling, so sibling differentiation is implied by scope 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?

"The caller's own" implies this is the read path for reminders you own, and the sibling names set_task_reminder / delete_task_reminder hint at the write counterparts, but the description does not say when to use this versus list_tasks or list_my_notifications. Usage is inferable, not 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 cover the read-only, idempotent, closed-world safety profile, so the description is free to add the non-obvious constraint that the active workspace is fixed by the session token and cannot be changed via this tool. That is genuinely useful behavioral context beyond the annotations, though it says nothing about result size or 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?

Two sentences: the first defines the operation and its return contents, the second delivers the session-pinning caveat. Nothing is redundant and the core purpose 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?

With no output schema, the description carries the burden of explaining returns, and it does so at the field level (role, active/owned). What remains unstated is the response shape (list vs. envelope) and whether results are paginated, which is minor for a small, parameterless list tool.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. The baseline of 4 applies; the description correctly implies a no-argument 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?

States a specific verb and resource ('List every workspace the caller belongs to') and also specifies what each entry carries (role, active/owned flag). This is clearly distinguishable from sibling tools like list_users or whoami, which address different resources.

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

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

The second sentence gives real operational context: the connector acts in the workspace pinned in the session token, and switching requires re-authentication. That tells the agent when this tool's output cannot be acted on directly, though it does not name an explicit alternative tool.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world, so the bar is lower; the description adds the calling role requirement and the fact that guests see only granted projects read-only. No mention of pagination or result size, which keeps it from a 5.

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

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

Front-loads the action and the key output distinction, then supplies the guest definition and auth requirement. The second sentence is dense but every clause (seat, sign-in, read-only scope, role) is load-bearing for correct interpretation.

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-param read-only list tool with full schema coverage and annotations, this is nearly complete; it also hints at return content (per-guest project read flag). It does not describe ordering or result limits, which prevents a 5.

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

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

Only one parameter and its schema description coverage is 100%, so the schema fully documents projectId. The description adds nothing about the parameter itself, 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 and resource (list the workspace's guests), plus the distinguishing output detail that each guest is marked with project read access. That separates it from list_users and list_invitations without needing 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?

Gives clear context (guests of this project, requires Administrator or ProjectManager) and points at create_invitation role=Guest for the creation path. It does not explicitly state when-not-to-use or contrast with set_project_guests/list_users, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety behavior is well covered. The description adds that results are returned as the API's JSON array and are scoped to the active workspace, but it does not mention pagination, ordering, result limits, or 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?

Two compact sentences with no wasted wording. The primary action and scope are front-loaded, and the return format is mentioned briefly.

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 simple, parameterless, read-only list tool with rich annotations. Because no output schema exists, the description could say more about the shape of project objects or pagination behavior, but for a low-complexity list operation the description is largely complete.

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

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

The tool has zero parameters, so there is no parameter semantics for the description to clarify. The baseline for a parameterless tool is 4.

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

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

The description uses a specific verb (List) and resource (projects), and adds scope: the caller's active Madda Tasks workspace. It implicitly distinguishes itself from get_project (single project), though it does not explicitly name siblings such as get_project or list_tasks_by_project.

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 (listing all projects in the active workspace) is implied but not framed as when-to-use guidance. There is no explicit comparison to get_project, list_tasks_by_project, or other list tools, and no when-not-to-use condition.

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 readOnly, idempotent, non-destructive and closed-world, so the bar is lower; the description still adds real value by naming the fields surfaced per item (owner, due date, score, response) and by disclosing the failure mode on Free plans. It stops short of describing ordering, pagination, or what an empty register returns.

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

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

Two tight sentences with no filler, front-loaded with the core action and scope, followed by the plan constraint as a secondary note. Every clause carries information an agent needs.

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

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

For a simple, single-parameter read tool with rich annotations and no output schema, the description is nearly sufficient: purpose, returned fields, roles, and plan gating are all present. The only gap is the absence of any statement about result ordering or size limits.

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

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

There is a single parameter (projectId) at 100% schema description coverage, so the schema already carries the semantics. The description adds the concept of project scoping but no format or constraint detail beyond what the schema states; this is the baseline 3 case where structured data does the work.

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 supplies a precise verb and resource ('List a project's RAID register') and spells out the RAID acronym and the fields returned, so an agent can immediately distinguish it from create_raid_item/update_raid_item/delete_raid_item. It never explicitly names those siblings as alternatives, 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?

'Any team role. Pro plan only (a Free workspace gets a plan-limit message)' gives concrete caller preconditions and an explicit exclusion for Free workspaces. It does not, however, contrast this tool with other retrieval routes (e.g. list_projects or search_calls-style filtering), so when-to-use remains implicit.

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, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new context by disclosing that results are workspace-wide with no filtering and by listing the exact fields returned, though it says nothing about pagination, ordering, or result caps.

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: scope first, returned fields after the colon. 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 parameters and no output schema, the description does the necessary work by naming the returned fields, which is what an agent needs to decide whether to call it. It falls short only on result-set size/ordering behavior for a potentially large workspace-wide 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?

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. It correctly implies no filtering arguments exist by saying it lists every repeating task.

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 (List) and a precisely scoped resource (every repeating task in the workspace), and enumerates the fields returned (taskId, frequency, interval, endsOn, occurrence count). The 'repeating' qualifier implicitly separates it from list_tasks, but no sibling is named explicitly, keeping it 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?

Usage is only implied: an agent can infer this is the read-side counterpart to set_task_recurrence and stop_task_recurrence, but the description never says when to call it versus list_tasks or how to act on the results. No prerequisites, exclusions, or alternatives are 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?

Adds substantial context beyond the read-only annotations: returns the caller’s own views plus everyone’s shared ones, newest first, and config is stored as the app wrote it. The guest restriction is also a useful behavioral constraint.

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 front-loaded around the core listing behavior, with no wasted sentences. The clauses about config immutability and guest access each add useful scope or constraints.

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 one optional parameter and no output schema, the description supplies enough context to call it correctly. It covers scope, ordering, visibility, config handling, and guest restrictions.

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 projectId and its omission behavior. The description repeats the workspace-wide meaning but does not add syntax or format detail beyond that baseline.

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 saved views. It defines what a saved view is (named filter/group/sort settings across task list, board, table, calendar, or Gantt), which distinguishes it from the many list_* 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?

Clearly explains the projectId condition: provide one project’s views, or omit it for workspace-wide views. It also states that guests cannot list views. It lacks explicit alternatives, but there is no close sibling that lists saved views, so the guidance is effectively complete.

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