Onplana

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

Annotations already declare idempotent/readOnly=false/destructive=false, so the description earns credit for added context instead: the required permission scope, the active-org-member precondition, and the ENTERPRISE+ feature gate. The 'Idempotent' line slightly restates idempotentHint but the auth and eligibility constraints are genuine added value.

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?

Five short telegraphic sentences, front-loaded with the action and scope, then permission, idempotency, eligibility, and tier. Nothing is padded.

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, it covers permission, feature tier, and eligibility adequately. It doesn't state what happens on success/failure (e.g. already-a-member response) or the return payload, a minor gap.

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

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

Schema coverage is 100% with a single well-documented userId, so the baseline is 3. The description adds one eligibility constraint on that parameter's value ('must be an active org member') but no format or sourcing detail beyond what the schema 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?

Specific verb+resource+scope: 'Add a user to the org-level Change Control Board.' The 'org-level' qualifier cleanly distinguishes it from sibling add_project_member, so an agent can pick it 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?

Gives concrete preconditions for use: requires org.governance.manage (Admin+), the target must be an active org member, and the changeControl feature at ENTERPRISE+. It never names an alternative tool (e.g. list_ccb_members, update_member_role), so it stops short of 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 cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower; the description still adds the required permission, the deliberate absence of email sending, and the active-org-member precondition. It does not state the failure behavior when a userId is not an org member, 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?

Three sentences, front-loaded with the core constraint, then parameters, then permissions, then the negative routing case. Every sentence 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 3-param mutation with no output schema and annotations already declaring idempotency and non-destructiveness, this covers preconditions, permissions, and the alternative path well. Only the error/edge behavior (non-member id, duplicate add) is left unstated.

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

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

Schema description coverage is only 33% (userId documented, projectId not), so the description must compensate. It does add the userId lookup source and enumerates role values, but the enum is already in the schema and it adds no meaning for projectId, so compensation is partial.

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

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

States a specific verb and resource ('Add ... to a project') and constrains scope precisely: an EXISTING active org member, not a new invitee. This immediately distinguishes it from email-invitation flows among its many 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 explicit when-to-use (existing org member), an explicit when-not and alternative (brand-new email outside the org → use the invitation UI), a prerequisite permission (project.members.manage), and the lookup step (list_org_members first). Nothing is left to inference.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false), it adds real behavioral context: the required permission scope and, importantly, that a duplicate add returns an error so callers can detect duplicates. This is consistent with idempotentHint=false. It omits reversibility (whether/how membership can be removed) and invalid-id 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?

Three compact clauses: action, permission gate, duplicate behavior. No filler, and the purpose is front-loaded. The "(BUSINESS+ feature)" and permission abbreviations add density but earn their place as gating 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 2-param mutation with no output schema, the description covers purpose, authorization, and the notable duplicate-error behavior, which is enough to call it correctly. It could still say what the successful response contains and how to undo the membership.

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 portfolioId and projectId are already documented as ids in the schema. The description adds no parameter-level detail (formats, cross-references, constraints), 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 pair ("Add a project to a portfolio"), which is unambiguous and distinct from sibling add_project_member, create_portfolio, and update_portfolio. It does not explicitly name or contrast with any alternative tool, so it stops short of the top score despite the clear operation.

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 gating prerequisite (requires org.portfolio.manage, default Manager+, BUSINESS+ feature) but no when-to-use/when-not guidance or named alternative for adding membership. Usage is implied by the operation name rather than stated, making this minimum viable.

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 this is a non-read-only, non-destructive write; the description adds genuinely new behavior: atomic all-or-nothing rollback, project inheritance from the parent, the returned ids, and the 25-item cap. It could optionally reconcile why the tool is retry-safe via idempotencyKey while idempotentHint is false, but the disclosure is well above the annotation baseline.

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

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

Four short sentences, front-loaded with what it does, then side effects, then the routing advice. Every sentence adds new information with no filler.

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

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

With only 3 parameters, no nested output schema, and full schema coverage, the description covers everything an agent needs: parentage, inheritance, limits, return value, and transaction semantics.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds one rule not in the schema (children inherit the parent's project) and restates the 25-item cap, which slightly deepens understanding of the array 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?

Specific verb (create) plus resource (subtasks) plus the constraint that they hang under an existing parent task with inherited project. This cleanly separates it from create_task and bulk_create_tasks, both of which appear 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?

Explicitly routes the agent: 'Use this instead of calling create_task repeatedly when decomposing a claimed task,' and gives the reason (single transaction, single budget slot). It names create_task as the alternative but never addresses bulk_create_tasks, the other obvious sibling for multi-task creation, so the when-not coverage is incomplete.

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 non-readonly, non-destructive, idempotent, and closed-world behavior; the description still adds real value with the OWNER/ADMIN authorization requirement, active-member eligibility rule, and PRO+ feature gate. It redundantly restates idempotency, which the annotation already conveys, keeping it out of 5 territory.

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 short sentences with the core action front-loaded and constraints trailing; no filler, no restated title, and every sentence carries a distinct rule.

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 and rich annotations, the description supplies purpose, permissions, idempotency, eligibility, and feature gating. Nothing an agent needs in order to invoke 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?

Schema coverage is 100%, so the single userId parameter is already documented as the 'Org member ID to designate as approver.' The description adds the constraint that the referenced user must be an active org member, which is a genuine eligibility rule beyond the schema text.

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

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

States a specific verb and resource ('Add a user to the designated timesheet approver list'), which unambiguously distinguishes it from list_timesheet_approvers and the approve/reject_timesheet_* siblings. An agent can identify the operation 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 — requires OWNER or ADMIN, target must be an active org member, and the timeTracking (PRO+) feature must be enabled — so the agent knows when the call will succeed. However, it names no alternative tool (e.g., list_timesheet_approvers or update_member_role) and states no explicit when-not condition, 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 and idempotentHint=true, so safety is covered. The description adds genuine beyond-schema context: advancing into a review stage seeds the gate-reviewer panel, the PROPOSAL_STAGE_CHANGED workflow-run dispatch is skipped on the agent path, and the 'governance' plan gate is required. It stops short of stating reversibility of destructive actions like reject/archive.

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 tool's purpose and then a compact action list where every clause carries transition or permission information. Slightly dense with parentheticals, but 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?

With 2 params, no output schema, and annotations covering safety, the description covers transitions, permissions, and side effects thoroughly. It could note the return shape or what happens to a proposal's data on reject/archive, but nothing essential for 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 0%, and the enum values alone ('submit', 'hold', etc.) are opaque without semantics. The description compensates well by mapping each action value to its source/target stage and its prerequisite role, which is the essential meaning an agent needs to pick the right action.

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 ("Drive a governance proposal through its lifecycle") and then enumerates the six actions with their exact state transitions. This clearly separates it from siblings like update_proposal, create_proposal, and get_proposal, which an agent could otherwise confuse with it.

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

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

Each action is annotated with the transition it performs and the required access level (e.g., submit is 'owner+; restricted', reject is 'gate-panel restricted at review stages'). That gives strong when-to-use guidance per action, though it never names a sibling alternative or explicitly excludes cases where a different tool is preferable.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: it is a single round-trip aggregation, and it explains the provenance and purpose of the `workspace` field (users arriving from another app). It does not discuss freshness/staleness of the snapshot or auth prerequisites, so it falls short of 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-loaded with the core purpose and well organized, but somewhat long. The 'collapsing whoami, describe_capabilities and describe_schema into a single call' clause is effectively repeated from the preceding sentence, and the closing workspace/why-it-exists sentence, while justified, 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?

With no input schema and no output schema, the description carries the full burden of explaining return values, and it does so thoroughly — identity/org/plan, capabilities counts, schema index, task count, workspace URL, and web-only feature list. Nothing an agent needs to invoke 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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description mentions 'describe_schema(entity[, projectId])' but that documents a sibling's signature, not this tool's own inputs, so there is nothing further to clarify.

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

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

States a precise verb+resource ('cold-start summary for a fresh session, in one round-trip') and enumerates exactly what it returns (identity, org, plan features, capabilities summary, entity schema index, assigned-task count). It explicitly distinguishes itself from siblings by naming the three tools it collapses (whoami, describe_capabilities, describe_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 frames the use case ('fresh session', 'one round-trip') and routes the agent to alternatives for deeper needs: describe_capabilities for per-tool gates, describe_schema for field shapes, list_assigned_tasks for the full queue. Both when-to-use and when-to-use-something-else are covered.

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

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

Goes well beyond the annotations by spelling out the merge algorithm: untouched open AI risks are updated, human/agent-edited or dismissed risks are skipped, the remainder are added, and nothing is removed. It also states the authorization requirement ('write access to the project, as for create_risk'), which annotations cannot convey.

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

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

Three tight sentences, front-loaded with the action and effect, then the merge rules, then the usage triggers. No filler and every sentence 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?

With no output schema, the description could say what the call returns (counts of added/updated/skipped findings) and whether repeat runs behave the same given idempotentHint=false. Otherwise the mutation semantics, permissions, and triggers are complete enough to call 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?

There is one parameter (projectId) with 0% schema description coverage, and the description never says whether it takes an ID, key, or name or where to obtain it. Referencing 'Project X' implies a single project scope but adds no format or lookup guidance, so a gap remains.

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 ('Run AI risk analysis on one project') and immediately names the effect ('merge the findings into its risk register'), distinguishing it from create_risk and list_risks by describing merge semantics rather than single-entry creation or listing.

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 two concrete triggers ('what could go wrong on Project X', before sprint planning) and points at list_risks for viewing and create_risk for the permission model. It stops short of an explicit exclusion (e.g. 'do not use for manually adding a single risk — use create_risk'), so it is strong context rather than full when/when-not routing.

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 declare readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds genuinely new behavioral facts: append-only with no undo, and that supplying taskId triggers a real-time UI broadcast so humans see the line land. It does not mention the schema's idempotencyKey retry behavior, which is the one 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?

Dense and front-loaded: purpose first, then required params, then the optional broadcast behavior, then the append-only caveat. Sentences are long but each carries information; nothing 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?

With no output schema and six parameters, the description covers the four required fields, the mutating append-only nature, and the taskId broadcast side effect. Only the optional idempotencyKey is left entirely to the schema, which documents it fully, so this is nearly complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema for taskId: it explains the side effect (real-time UI broadcast) rather than just 'task this line is about.' The rest of the parameter commentary largely restates schema constraints (level <=8 chars, text <=4000 chars, monotonic lineNum).

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 precise verb+resource+scope: 'Append a streaming progress log line to the current agent conversation.' No sibling tool does log streaming, so an agent can identify this immediately 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 implied by the framing ('streaming progress log line to the current agent conversation') and it enumerates required fields, but it never states when to choose this over siblings like create_comment or create_issue, nor any when-not condition. Adequate but leaves routing 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 the safety profile (readOnly=false, idempotent=true, destructive=true, openWorld=false). The description adds valuable context beyond them: the authorization requirement (eligible approver roles/designation), a feature gate (timeTracking PRO+), and a state precondition (entry must be SUBMITTED). It stops short of explaining what happens on success or whether approval is reversible, but that is a meaningful supplement.

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

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

Three short sentences, front-loaded with the action, followed by eligibility and feature gating. No filler; every sentence earns its place.

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

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

For a low-complexity single-parameter mutation with no output schema, the description covers the action, authorization, gating, and precondition well. The remaining gap is outcome/error behavior (e.g., what if the entry is not submitted), which annotations alone do not resolve.

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 0% for the single entryId parameter, so the schema itself adds no meaning. The description implies entryId refers to a submitted timesheet entry, giving marginal semantic context, but does not describe the ID's format or source, leaving the burden mostly unmet.

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 ('Approve a single SUBMITTED timesheet entry') with the entry state constraint front-loaded. It implicitly contrasts with the sibling approve_timesheet_week via 'single ... entry', but never names the alternative explicitly, so sibling differentiation is inferential 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?

Provides the caller eligibility conditions (OWNER/ADMIN/MANAGER in managers mode, or a designated approver in approvers mode), which is solid context. However, it gives no explicit when-to-use vs approve_timesheet_week or reject_timesheet_entry, and no when-not guidance, so usage routing 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 the write/destructive/idempotent profile, so the bar is lower. The description adds real value beyond them: it limits effects to SUBMITTED entries, requires approver eligibility, and flags the PRO+ feature gate. It stops short of explaining what happens to non-submitted entries or whether approval is reversible.

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, front-loaded sentences carry the scope, the eligibility requirement, and the feature gate 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 mutation tool with no output schema, the annotations plus description cover scope, precondition, and gating. It does not state the result of the call (e.g., what the bulk approval returns or whether partially-submitted weeks error), which is the only meaningful 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 parameters (userId, weekStart) are already documented in the schema. The description adds no format or constraint detail beyond what the schema provides, 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 (bulk-approve), resource (timesheet entries), and scope (all SUBMITTED entries for a specific user in a given week). The 'bulk/week' framing cleanly distinguishes it from the singular approve_timesheet_entry 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?

Provides a clear precondition ('Caller must be an eligible approver') and scopes the operation to SUBMITTED entries only. It does not explicitly name alternatives (e.g., approve_timesheet_entry, reject_timesheet_week), so usage context is clear but without exclusions.

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 that the project becomes read-only, that writes fail with PROJECT_ARCHIVED, that it is hidden from lists unless archived items are requested, that nothing is deleted, that unarchive reverses it, and that readiness checks return READINESS_GAPS under BLOCK mode. Also states the required roles and permission (Owner/Manager or org.compliance.manage).

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 primary effect (read-only, hidden) before the exceptions and roles. Dense but virtually every clause carries operational information; only the dense packing of readiness-mode and role details slightly hurts scannability.

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 still covers return behavior (verdict returned in WARN mode), error codes (PROJECT_ARCHIVED, READINESS_GAPS), reversibility, and authorization requirements, which is everything needed to invoke 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 0% and the single required projectId parameter is not described in the description or schema. The parameter is self-evident from its name, so the gap is minor, but the description adds no 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 (archive), resource (project), and precondition (completed or cancelled project), and names the reversing sibling unarchive_project. An agent can immediately distinguish it from delete_project and create_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?

Gives the condition that makes archival appropriate (project is completed/cancelled), names unarchive_project as the reversal, and explains the readiness-gate behavior under BLOCK/WARN. It does not explicitly say when to prefer delete_project instead, but the 'nothing is deleted' framing covers the main confusion.

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=true, so the safety profile is covered. The description goes beyond them by specifying the idempotent behavior concretely — a duplicate assignment succeeds as a no-op and returns alreadyAssigned: true — and by stating the access requirement. No error/rate-limit detail, but solid added context for a mutation 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?

Three short sentences, front-loaded with the operation, then the exclusivity rule, then the permission and no-op semantics. Every sentence 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?

With no output schema, the description usefully discloses the alreadyAssigned result field. All three parameters are accounted for, the mutual-exclusion rule and access requirement are stated, and nothing needed 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?

Schema description coverage is 100% and the mutual-exclusivity of taskId/projectId is already written into the schema property descriptions, so the description mostly restates it. It does reinforce the constraint in prose, but adds no syntax, format, or default information 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 (assign) and resource (tag) plus the two target entity types, so the operation is unambiguous. It does not name the inverse sibling unassign_tag or distinguish itself from create_tag, but the core purpose is fully clear.

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?

Explicit constraints: provide either taskId or projectId but not both, and the caller must have access to the target entity. There is no routing advice to alternatives (e.g., unassign_tag), but the preconditions for correct invocation 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 annotations: required permission (task.assign on the project), target precondition (active org member), the CONFLICT failure mode for expectedAssigneeRevision, and the returned claimRevision that enables chained optimistic-concurrency assigns. With destructiveHint=true already declared, this level of precondition and error disclosure is more than the annotations carry on their own.

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 and the unassign idiom, then layers concurrency and capacity detail in a logical order. It is a single dense paragraph running well over a hundred words, and the `load` payload sentence could be tightened, but every sentence carries information the agent can act on.

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

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

There is no output schema, and the description compensates by documenting the return shape (assignee id and name, claimRevision, and the capacity/load block including over, overBy and otherWork). It also covers permissions, target preconditions, error semantics and dryRun pairing, leaving no material gap for a five-parameter 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 schema already documents all five parameters and the baseline would be 3. The description nonetheless adds operational meaning the schema states only tersely: why email resolution exists, how expectedAssigneeRevision fails and how claimRevision is meant to be reused for chaining.

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 ('Assign or unassign one task') and immediately delimits scope to a single task, which distinguishes it from the sibling bulk_assign. The unassign path is described in the same breath, so the agent knows this tool covers both directions.

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 guidance on when to reach for assigneeEmail versus assigneeId, including the rationale ('when the agent only knows the user's email and would otherwise need a separate list'), and states the two are mutually exclusive. It does not, however, name tool-level alternatives such as bulk_assign or propose_assignment, so routing between sibling tools 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 only cover the coarse profile (openWorldHint=true, destructiveHint=false), so the description carries real additional value: server-side fetch semantics with SSRF protection (internal/private addresses blocked), a 50 MB cap, no-truncation guarantee, and an authorization tier requirement. These are exactly the failure modes an agent needs to know 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?

Six compact sentences, each carrying a distinct fact (mechanism, routing rule, size limit, optional param, alternative tool, permission). The purpose and mechanism are front-loaded before the 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 4-parameter create tool with no output schema, the description covers the mechanism, preconditions, limits and the competing sibling. Since there is no output schema, it does not need to describe return values, and the idempotency/replay behavior is fully documented in the schema.

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

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

Schema coverage is 100%, so url, taskId, fileName and idempotencyKey are already documented at the schema level. The description restates only the fileName derivation rule and the public-URL constraint, both of which the schema already states, so it adds no meaningful syntax or format detail beyond the 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 ('Attach a file to a task by URL') and immediately explains the mechanism — the server fetches the bytes rather than the model. It contrasts itself with the sibling 'upload_task_attachment' so an agent can route correctly 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 explicit when-to-use ('when the file already lives at a URL — cloud storage, a public link'), an explicit alternative for the other case ('file that exists only in your sandbox, use upload_task_attachment instead'), and a permission precondition (contributor or above; VIEWERs cannot). Nothing is left to inference.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower, and the description still adds real value: the stored object is metadata-only with zero bytes, and the call requires project.content.create on the parent library's project with viewers being read-only. It stops short of saying what happens on a duplicate URL or what the response 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?

Four tight, front-loaded sentences with no filler; the key distinction ('Zero bytes, just a metadata row') comes early. A small amount of space is spent re-listing the enum values already present in the schema.

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

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

For a create-type tool with no output schema and no annotations covering parameters, the description covers permissions and storage behavior but omits what is returned (e.g., a document id) and duplicate-URL handling. It is adequate to invoke the tool but not fully complete.

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

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

Schema coverage is only 50%, so the description should compensate for the undocumented parameter (libraryId), but instead it restates the provider enum and the http(s) URL rule that the schema already carries. libraryId is only obliquely covered by 'inside a library' / 'parent library's project', leaving the actual gap unaddressed.

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

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

The description states a concrete verb and resource ('Attach an external URL as a WorkspaceDocument inside a library') and immediately clarifies the shape of what is created ('Zero bytes, just a metadata row'). However, it does not distinguish this tool from the near-identical siblings attach_file_from_url and attach_sharepoint_document, leaving the agent to guess which one applies to a given source.

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 constraints ('url must be http(s)', provider enum), and the permission requirement tells the agent who can call it. But there is no explicit when-to-use/when-not guidance and the closest alternatives (attach_file_from_url, attach_sharepoint_document) are never mentioned despite overlapping function.

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 supply the generic flag set; the description adds real substance: what Onplana persists (URL + metadata only), what is explicitly not done (no download/copy in V1, framed as a security stance), and the auth requirement. This is well beyond annotation coverage.

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

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

Front-loaded with the operation and the LINK semantics, then the no-copy constraint and auth note. Four tight sentences with little waste, though the parenthetical '(security stance)' and repeated 'no download/copy' framing is mildly 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?

Behavior, storage model, and prerequisites are complete for a mutation tool, and there is no output schema to explain. The remaining gap is purely parameter-level: four undocumented identifiers with no schema descriptions.

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

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

Schema description coverage is 0% and the description documents none of the four identifiers. It hints that siteId refers to a SharePoint site, but libraryId, driveItemId, and projectId are left entirely for the agent to infer, and no format or ID-source guidance is given.

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 (attach), resource (SharePoint document), and destination (Onplana project workspace), and pins the exact mechanism (LINK reference, externalProvider=SHAREPOINT). This cleanly separates it from upload-style siblings and from generic attach_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 a clear prerequisite ('caller must have read access to the SharePoint site') and the V1 security stance that no file is copied, which constrains when this is the right choice. It stops short of explicitly naming alternatives like attach_link or upload_library_document and the condition that selects them.

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/idempotentHint already covering the safety profile, the description still adds substantive behavior: a 100-value-per-dimension cap, the full clientSurface enum with the non-obvious 'NONE' bucket for rows recording no client, and the required permission gate (OWNER or ADMIN + auditLogs feature). That is auth, result-shaping, and edge-case behavior well beyond 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?

Front-loads what is returned, then purpose, then the enum/cap/permission details; every sentence carries information. The parenthetical enum list is long but directly serves the stated 'build filter chips' use case, so it earns its space.

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 zero params and no output schema, the description correctly carries the burden by describing the returned shape (distinct values plus per-value row counts) and its limits. It covers enough to call the tool correctly, though it does not say whether all results come back in one call or how counts are scoped.

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, so the baseline is 4; the description's discussion of dimensions is about output rather than input semantics. Nothing is missing on the input side.

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

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

States a precise verb+resource: returns the distinct action, resource, and clientSurface values logged by the caller's org, with row counts per value. Names the enum domain and the sibling relationship to `list_audit_log`, so an agent can distinguish it from list/export/get audit tools 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?

Explicitly frames the use case — building filter chips before a follow-up `list_audit_log` call — which is clear, actionable context. It stops short of stating exclusions (e.g., when the enums are already known, or how it relates to `export_audit_log`/`get_audit_entry`), so it falls just below full when/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?

Adds substantial behavior beyond the annotations: it writes/persists findings, is idempotent through dedupe, returns the count of NEW risks inserted (0 when all already exist), and performs no LLM call or plan gate. The return-count disclosure is especially valuable given there is no output 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 the action and destination, then a compact detection list, then idempotency/return behavior, then usage triggers. Every sentence carries distinct information 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?

With no output schema, the description compensates by explaining what is returned (count of new risks). Combined with the detection rules, idempotency, and usage conditions, an agent has everything needed to invoke and interpret the call.

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 documents projectId fully. The description implies the scan target is a project but adds no format or syntax detail beyond the schema field. 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 ('Run deterministic schedule-risk detection on a project') and enumerates the exact detection rules (overruns, overdue tasks, >30% unassigned, stuck-at-99%). It also names where results go ('persist ... to the Risks tab'), so it is distinguishable from siblings like get_schedule_risk and analyze_project_risks.

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 triggering contexts ('Use after import or when the Risks tab is empty and the user asks ...') and rules out LLM-based/plan-gated alternatives via 'No LLM call, no plan gate'. It stops short of naming the specific sibling tools it is an alternative to (e.g., analyze_project_risks, compute_risk_patterns).

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 (destructiveHint=true, idempotentHint=false), and the description adds valuable context beyond them: apply captures a 'Before AI Schedule Proposal' baseline and commits all dates in one atomic operation. It also discloses the 100-task cap, feature gate, and 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-loads purpose, then the workflow, then constraints. Dense but every sentence earns its place, though the trailing 'Cap: 100 tasks. Feature: aiAdvanced (PRO+).' fragments are slightly terse.

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 carries the return-behavior burden, and it adequately explains the preview-then-apply contract, atomic commit, and baseline capture. Nothing critical 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%, so the baseline is 3, but the description adds workflow meaning to mode beyond the schema's per-parameter text (preview then apply) and frames when apply is safe. previewId and leveling details are already well covered in 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 (auto-schedule/propose) and resource (project schedule) with scope: fits all tasks before a target deadline while respecting dependencies. It is clearly distinguishable from siblings like gantt_optimize, resource_leveler_analyze, and propose_deadline_extension.

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 prescribes the multi-turn workflow: call mode="preview" first, then mode="apply" after the user confirms. It also states prerequisites (project Owner or Manager role for apply), a task cap, and the PRO+ feature gate.

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 substantial context beyond them: the partial-success model (updated/skipped/errors), the meaning of each bucket, per-task error codes (NOT_FOUND / PROJECT_ACCESS_DENIED), and the 200-task cap. This is exactly the write-behavior disclosure an agent needs.

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 purpose sentence, then parameters/alternatives, return shape, limits, and permissions in a logical order. Every sentence carries distinct information (mutual exclusivity, return buckets, error codes, cap, permissions) with no padding.

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

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

With no output schema, the description discharges the return-value burden by describing the { updated, skipped, errors } shape and error codes, and it covers limits and auth requirements for a mutation tool. Nothing an agent needs to invoke 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?

Schema description coverage is 100%, so the mutual exclusivity of assigneeId/assigneeEmail, the null-to-unassign semantics, and email resolution are already documented in the schema. The description largely restates these, so the baseline 3 for a fully-covered schema 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+scope: '(un)assign multiple tasks to one person in a single call.' It also distinguishes itself from the sibling assign_task by naming the exact differentiating capability (optimistic concurrency via expectedAssigneeRevision), so an agent can tell the two apart 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?

Names the alternative explicitly ('Use the single-task assign_task when you need optimistic-concurrency') with the condition that selects it, and states the caller prerequisite (task.assign on each project) plus the target constraint (active org member). Nothing about routing or eligibility 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 declare readOnlyHint=false/destructiveHint=false, but the description adds substantial behavioral context the annotations do not: single all-or-nothing transaction, no scheduling/dates unless set per task, no durations or predecessors support, and collaborator failures reported as warnings. The idempotencyKey explanation is consistent with idempotentHint=false (opt-in retry safety), not a contradiction.

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

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

Front-loads the core action and scope in the first sentence, then layers exclusions and alternatives. Despite its length, nearly every sentence carries non-redundant routing or behavioral information, so the size is justified by the tool's complexity.

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 5-parameter batch mutation with no output schema, the description covers transaction semantics, scheduling limitations, dependency handling, and even the response's `url` field plus a directive to show the link. 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?

Schema coverage is 100%, so the schema carries the parameter baseline. The description still adds meaning by clarifying that tasks land with NO dates unless startDate/dueDate are set on each item, which reframes how the date fields must be used. It does not go deeper on sprintId/epicId or idempotency edge cases beyond what the schema 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?

States a specific verb and resource with scope: 'Add a list of up to 50 tasks to an existing Onplana project in one call, at the project root or under a sprint / epic.' It also explicitly distinguishes itself from siblings create_task (single), add_subtasks (children of existing task), and instantiate_plan (scheduling), so an agent can route 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 usage triggers ('add these tasks to my launch project', a checklist pasted into chat), names the alternative for scheduling ('Use instantiate_plan instead'), and clarifies the dependency workflow ('create the tasks first, then add each dependency with link_dependency'). When-to-use, when-not, and alternatives are all 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 annotations: unknown column ids are refused, per-call limits of 200 rows and 3000 cells (whichever hits first, with the wide-vs-narrow list implication), append order is preserved, and the batch is atomic ('the whole batch lands or none of it does'). Annotations only supply the generic write/non-idempotent/non-destructive profile, and nothing here contradicts them.

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

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

Front-loads the purpose and the sibling contrast, then packs value-format, validation, limits, ordering, and atomicity into tight clauses with no filler. Every sentence carries distinct operational 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 2-param, no-output-schema tool, the description covers validation, limits, ordering, and atomicity — the traits an agent needs to call it safely. It omits what the call returns (e.g., created row ids) and any permission prerequisites, which is a minor but real 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 only 50% (tableId undocumented), and the description compensates thoroughly for the opaque `rows` array: each entry is a map of columnId to value with types (string|number|boolean|null), columns may be omitted, and unknown column ids are rejected. This adds substantial meaning beyond the schema's terse 'map of columnId -> 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?

Specific verb+resource ('Append many rows to a workspace list (table) in one call') with explicit contrast to the single-row sibling create_workspace_row, so an agent can route between the two without opening schemas. The parenthetical '(table)' disambiguates the resource name.

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

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

The description explicitly frames the alternative ('where create_workspace_row appends a single row per call'), making the bulk-vs-single choice clear. It stops short of stating when not to use it (e.g., updates should use update_workspace_row, or that it only appends and cannot modify existing rows).

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 destructive/idempotent/non-readonly, and the description layers on genuinely new behavior: the return shape { updated, skipped, errors } for partial-success observability, skip-vs-error semantics for unauthorized tasks, and a single parent-auto-close rollup per batch rather than per task. These are consequential side-effect details the annotations do not 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?

Five tight sentences, each earning its place, with the core purpose and the update_task alternative front-loaded. 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?

No output schema exists, but the description supplies the return shape and partial-success semantics, plus batch limits and side-effect behavior. Nothing an agent needs to invoke 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?

Schema description coverage is 100%, so dryRun, status, and taskIds are already fully documented, and the description's 'Up to 50 task ids per call' merely restates maxItems: 50. It adds no syntax or format meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Flip status on multiple tasks in one call') and immediately distinguishes itself from the single-task sibling update_task. An agent can tell exactly what this does and how it differs from update_task and bulk_update_tasks 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?

Explicitly routes the agent: 'Use this instead of N update_task calls when marking siblings DONE / blocking a batch / reopening a set.' It names the alternative and the conditions that select this tool, covering when-to-use and when-to-use-something-else.

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/readOnlyHint/idempotentHint, but the description adds genuinely new behavior: a hard batch cap of 50, partial-failure semantics ('per-task failures are reported in `errors` but do not abort the whole call'), and the required permission. It stops short of explaining rollback scope or what a successful response body contains, keeping it at a strong 4 rather than 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 purpose, then parameters, then failure/permission semantics, then the alternative tool – a logical order with almost no filler. The priority definition duplicates the schema's own wording, a minor redundancy that keeps it just under 5.

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

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

There is no output schema, and the description compensates by naming the `errors` field for partial failures and by specifying the batch limit and permission. Combined with the alternative routing, an agent has everything needed to invoke and interpret the call 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?

With 80% schema coverage the baseline is 3, but the description adds real meaning: priority is explained as a ranking label that does NOT drive the critical path (a subtle and valuable disambiguation), and shiftDueDateDays is clarified as a relative signed offset. taskIds and status simply restate 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 ('Apply the same partial update to many tasks at once') and immediately distinguishes itself from bulk_update_status by name. An agent can tell it apart from update_task (single) and bulk_update_status (status-only) 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?

Explicitly names the alternative and the condition that selects it: 'PREFER bulk_update_status when the ONLY change is status (cheaper, atomic, single parent-rollup pass)'. It also states the permission prerequisite (task.edit.any per project), so the routing decision needs no 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 cover the read-only/idempotent safety profile, but the description adds substantial context beyond them: the currency-conversion condition for billable-rate orgs, the exact null-behavior of CPI/CV/EAC/ETC/VAC when no actual cost is recorded, the actualCostRecorded=false flag, and the instruction to report those as N/A rather than 'on budget'. It also discloses authorization and plan-gate requirements.

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

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

Front-loaded with purpose and scope, then progressively less critical detail (return fields, null semantics, routing preference, access, plan gate). Dense but every sentence carries operational information; the null-handling and routing clauses are somewhat compressed into long multi-clause sentences.

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, but the description enumerates the returned metrics and, importantly, explains the null/flag semantics that would otherwise be misinterpreted. Combined with the access rules and plan gate, an agent has everything needed to call it correctly and interpret 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 50% — asOf is documented ('ISO date; defaults to now.') while projectId has no schema description. The description confirms asOf's default and scopes projectId to a single project, which partially compensates, but adds no format or constraint detail for projectId. Baseline 3 for a partially covered schema.

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

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

States a specific verb+resource+scope: 'Earned Value Management report for one project as of a given date'. It enumerates the returned metrics (BAC, EV, PV, AC, CPI, SPI, EAC, ETC) and explicitly distinguishes itself from the sibling calculate_evm_history, so an agent can disambiguate without opening a schema.

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

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

Gives an explicit alternative and the condition that selects it: 'PREFER `calculate_evm_history` for time-series'. It also states the access prerequisites (org OWNER/ADMIN or budget.read at project role) and the aiAdvanced plan gate, so an agent knows both when to route elsewhere and whether the caller can invoke it at all.

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 the description adds substantial non-obvious behavior: the exact contents of each point, that `points` is empty when `dataSource` is "none", the reason (no imported costs, rate card or default rate), and the access/plan gate requirement. This is real behavioral disclosure beyond the structured fields.

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?

Return shape is front-loaded and every sentence carries information (division of labor, gating, empty-result rule). The final sentence is dense, with a nested parenthetical about pricing hours, but it is not padding.

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

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

With no output schema, the description fully covers what the agent needs: the point structure, the empty-result edge case and its cause, the access/plan prerequisite, and the sibling boundary. Nothing required to invoke 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?

Schema coverage is 0% for the single `projectId` parameter, so the description carries the burden; it implies scoping to 'one project' but gives no id format or source. It also references `dataSource`, which is not an input parameter, which could momentarily confuse an agent about what it can pass.

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 ('EVM time-series for one project') and enumerates the returned series (date, PV, AC / S-curve). It explicitly demarcates itself from the closest sibling by saying CPI and estimates live in `calculate_evm`, so an agent can pick between them 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 clearly assigns the CPI/estimate use case to `calculate_evm` and describes this tool as powering S-Curve and trajectory analyses, plus notes the shared access and plan gate. What it lacks is an explicit negative case or trigger phrasing (e.g. 'use this when you need the trend over snapshots, not a point-in-time index').

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 contributes real extra context: only in-progress runs are affected, the caller needs manage permission, and the feature requires a PRO+ 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?

Three short sentences, action front-loaded, then the eligibility constraints. Nothing is padded and no sentence 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?

For a one-parameter destructive tool with full annotation and schema coverage, the description covers scope, permissions and feature gating adequately. It omits what happens after cancellation (reversibility, effect on running tasks), which is a minor gap rather than a blocking one.

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

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

There is a single parameter with 100% schema description coverage, so the schema fully documents runId. The description adds no format, source, or lookup guidance for the ID, and per the high-coverage baseline a 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 ('Cancel an in-progress workflow run') and constrains scope to in-progress runs, which cleanly separates it from list_workflow_runs and get_workflow_run. It does not name a sibling explicitly, so it falls short of the top band.

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?

Adds a permission prerequisite ('caller must be able to manage the workflow') and a plan gate ('automations (PRO+)'), which tells the agent when the call will succeed. However, it never contrasts this with alternatives such as decide_workflow_approval or test_run_workflow, so usage is only implied.

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

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

Annotations already disclose the safety profile (not read-only, not idempotent, not destructive, closed-world). The description adds real value beyond them: the authorization requirement, plan availability, and exactly what data the snapshot freezes. It stops short of saying whether repeated captures create multiple baselines or what the returned snapshot contains.

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 that front-load the action and scope, then append the authorization and plan constraints. No filler, no repetition of the schema.

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

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

With no output schema and a trivial two-parameter input, the description supplies the essentials: what is captured, who may call it, and availability. It lacks any statement of side effects (does capturing a baseline alter project state, or how it relates to existing baselines), which is the only meaningful 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 50%: `name` is documented in the schema (with its default), while the required `projectId` has no description anywhere. The description mentions no parameters at all, so it does not compensate for the undocumented required field, though `projectId` is self-explanatory.

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

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

States a specific verb ("Capture") and resource ("point-in-time baseline snapshot of a project") and enumerates the captured content (tasks, dates, progress, EVM). It is clearly distinguishable from get_baseline/compare_baseline/list_baselines by action, though it never names those siblings to reinforce the distinction.

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 strong prerequisites ("Caller must be a project Owner or Manager", "Available on every plan") which help an agent decide whether the call can succeed. However, it offers no guidance on when to snapshot versus when to read or compare existing baselines, so alternative-selection is left 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 only say non-read-only, non-destructive, idempotent; the description goes far beyond with lease expiry semantics (10 minutes, self-lapsing so a crashed agent cannot block a task), all three return shapes including the already-DONE case, the fact that a lease grants no permission, and the exact permission requirements (task.edit.any / task.edit.own).

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 purpose and the mutual-exclusion rationale, then layers return values, lease lifecycle, related tools, and permissions in a compact sequence. Every sentence carries distinct information; none 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?

There is no output schema, so the description must carry return values, and it does so completely (claimed true/false, competing agent, DONE status with change time). Combined with lifecycle, alternatives, and auth, an agent has everything needed to call this 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% and the schema already documents ttlMinutes with its default of 10 and cap of 60. The description's mention that it 'sets a different lifetime' adds no syntax or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Take an exclusive execution lease on one task') with the exact scope and motivation ('so a second agent on the same board does not do the same work'). It explicitly separates itself from assign_task, which an agent might otherwise confuse with claiming work.

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 when-to-use ('before working on it'), the ongoing cadence ('call renew_task_lease about every 3 minutes'), the termination step ('release_task when finished'), and the alternative for a different need ('use assign_task for ownership'). Nothing about routing between siblings 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 carry the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real value: the summary is 'built without AI, the same text the Baselines tab shows' (deterministic, reproducible output), duration variance uses the stored planned duration rather than the date span, and availability is stated.

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 tool's purpose and result shape in the first sentence, and the routing hint and availability note come last. It is dense and long, but with no output schema the field enumeration earns its space; only the double-length first sentence 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?

With no output schema and one undocumented parameter, the description does the compensating work: it enumerates every returned field and describes the summary contents down to the 'five largest start or finish moves'. An agent can reason about the result without inferring anything.

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

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

Schema description coverage is 50%: maxTasks is documented and baselineId is not. The description implies baselineId scope ('one of its baselines') and confirms the 'worst slippers' meaning of maxTasks, but adds no format or ID-source detail. Baseline 3 is right given partial schema coverage.

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

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

States a specific verb (computed variance) and resource (project against one of its baselines) and enumerates the exact outputs: finish slip in calendar days, RAG rating, task counts, worst slippers. It explicitly distinguishes itself from get_baseline, so an agent can route 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?

Names the alternative get_baseline and the condition for choosing it ('for the raw snapshot'), and notes availability ('Available on every plan'), which rules out plan-gating surprises. It stops short of an explicit when-not or prerequisite statement, so it lands just below the top band.

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 data it reads (BAC/EV/PV/AC/CPI/SPI/EAC), the write side effects (artifact persisted to the Agent Deliverables library and delivered to the Agent inbox), the return values (artifact id, conversation id), and the exact permission/contributor requirements for a non-destructive but mutating 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?

Purpose and delivery targets are front-loaded in the first sentence, followed by data sources, return values, and gating rules in a logical order. The 'Plan gate: aiCore (every plan)' fragment is slightly terse but each sentence carries usable 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 two-parameter mutation tool with no output schema, the description covers inputs, side effects, return identifiers, and access requirements. It does not address repeat-invocation behavior (annotations mark idempotentHint=false, implying duplicate artifacts) or failure modes, which would complete the picture.

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

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

Schema description coverage is 100% and both parameters (projectId, locale with its enumerated language list) are fully documented in the schema. The description adds no additional parameter semantics, 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?

Names a specific verb and resource ('Generate a plain-language EVM narrative for a project') and states the delivery destinations (Agent inbox, Agent Deliverables library). It does not explicitly distinguish itself from related siblings like calculate_evm, critical_path_narrative, or leveling_narrative, 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?

Gives concrete preconditions for use: the aiCore plan gate, read access to project cost (org OWNER/ADMIN or budget.read at project role), and Contributor access on the project so the agent can save the draft. It stops short of naming when to prefer a sibling narrative tool or when not to use this one.

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

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

Goes well beyond the annotations: it enumerates exactly which live project facts are read (progress, task counts, 7-day completions, overdue, milestones, top risks/issues, recent tasks), what is written (goals/status/risks/milestones/decisions), the return values (artifact id, conversation id), the plan gate (aiCore), and access requirements (any project member). This is rich disclosure of side effects and prerequisites.

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 in the first sentence, followed by progressively more detail. The enumerated read list is long but each item is concrete and useful; no filler sentences. Slightly verbose but well structured.

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

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

For a compose/generation tool with no output schema, the description covers inputs read, output produced, returned identifiers, plan gate, and access — everything an agent needs to invoke it correctly. Nothing material is missing.

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

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

Schema description coverage is 100% and the single projectId parameter is fully documented in the schema, so the schema carries the load. The description adds only that the agenda is generated 'for a project', which does not significantly extend parameter meaning beyond what the schema provides.

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

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

States a specific verb ('Generate a structured meeting agenda') and resource (meeting agenda/brief for a project), so the agent can tell it apart from generic status tools. It does not, however, explicitly distinguish itself from close siblings like compose_meeting_invite or compose_status_digest. Clear verb+resource but no sibling differentiation.

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

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

The description implies usage via the deliver-to-inbox workflow ('deliver it to the Agent inbox for review') but never states when to choose this over compose_meeting_invite, compose_status_digest, or generate_status_report. No explicit when-to-use or when-not-to-use conditions are given. Implied context only.

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 annotations: the event is created without attendees because Microsoft auto-invites any event with attendees, the proposed attendees are placed in the body instead, the external attendee cap is 10, and the Calendars.ReadWrite scope is required. It also discloses the return payload since no output schema exists.

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 critical constraint (draft, no attendees) in the first two sentences and keeps every sentence informational. It runs slightly long, but no sentence is filler given the non-obvious Microsoft invitation behavior it has to explain.

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 return fields (event id, webLink, attendeesInvited, proposedAttendees) and covers the safety/scope profile. Only a few low-salience parameters (location, reminderMinutes, bodyContentType) remain undocumented, which is a minor gap.

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

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

Schema coverage is only 38%, and the description clarifies the semantically tricky 'attendees' parameter (proposed, listed in body, not invited) and adds the 10-external-attendee cap. However, subject, body, location, bodyContentType, reminderMinutes and the UTC datetime formats get no additional explanation, leaving half the parameters on the schema alone.

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 (Compose) plus resource and scope (a draft meeting in the authorized user's own Outlook calendar). The 'draft only, nobody is invited' clause sharply distinguishes it from send_outlook_message, post_teams_channel_message, and compose_meeting_brief.

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 defines the workflow: create the draft, open it via the returned webLink, add attendees and send from Outlook. It also states the negative case — 'Onplana has no step that sends a meeting invitation' — so an agent knows not to look for a follow-up send 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?

Beyond the annotations (which only declare readOnly=false, non-idempotent, non-destructive), the description discloses that a draft artifact is created and routed to the Agent inbox, that the return value is an artifact id plus conversation id, and the plan gate (aiCore) and access level (any project member). That is exactly the mutation-side 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?

Dense but front-loaded: the core purpose and window come first, then source-of-sections, output shape, edge case, return value, and gate/access. Every clause carries information, though the single long run-on 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?

With no output schema present, the description compensates by enumerating the output sections (summary, changes by area, known issues, next planned work), the empty-window behavior, and the returned ids. Combined with the access and plan-gate notes, an agent has everything needed to call 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?

There is a single parameter with 100% schema description coverage, so the schema already documents projectId fully. The description references 'a project' but adds no format or constraint detail beyond the schema, matching the baseline 3 for schema-carried parameters.

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

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

States a specific verb+resource (generate structured release notes for a project) and pins down the exact input scope (tasks marked done in the last 30 days, grouped by epic/theme). This scope naturally separates it from neighbors like compose_status_digest and compose_meeting_brief.

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 for use: current-window work, delivery to the Agent inbox for review, and the plan-gate/access conditions. It does not explicitly name an alternative tool or an exclusion case, 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 the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds genuinely new behavior: it writes a persistent artifact into a specific library, routes it to the Agent inbox for review, and returns artifact id plus conversation id. It also discloses two access rules an agent could not infer — the aiCore plan gate and the conditional CPI/SPI line tied to cost-read permission.

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?

Roughly four sentences, all front-loaded: purpose first, then mechanics, then return values, then the gate/access caveats. Dense but each clause carries distinct information; only the access/CPI sentence drifts slightly late for a caller-scoping 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 two-parameter mutation tool with no output schema, the description covers the essentials: what gets produced, where it lands, what is returned (artifact id, conversation id), when the call is permitted (plan gate, project membership), and the conditional cost line. The one real gap is sibling disambiguation against generate_status_report.

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%: projectId and locale are both documented, including the accepted language code list, so the schema carries parameter meaning. The description adds nothing about parameters beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource (generate a weekly project status report), the content it contains (health, accomplishments, risks, next steps), where it writes (Agent Deliverables library) and where it delivers (Agent inbox). What it does not do is differentiate itself from the sibling generate_status_report or week_status, so an agent cannot tell from this text alone which of those to pick.

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

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

Usage context is implied rather than contrasted: it says it is a weekly digest for review by an agent, and it states the plan gate (aiCore) and access level (any project member), which helps an agent decide if it may call at all. But there is no explicit when-to-use-vs-alternative guidance, which matters given generate_status_report, week_status and summarize_project all live next door.

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

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

With no output schema, the description carries the return-shape burden and does so fully: it names acceptedCount, dismissedCount, affectedProjects, and the verdict enum (recurring | frequently_dismissed | mixed). Annotations already cover the read-only/idempotent/non-destructive safety profile, so this adds genuine behavioral value on top.

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 with no waste, front-loading the aggregate action and scope before the return details and the optional parameter. Every sentence earns its place.

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

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

For a one-param read tool with no output schema, the description supplies the return fields, the verdict semantics, the widget purpose, and the lookback bound. Nothing needed 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?

Schema description coverage is 100% and the single optional param is already documented as '1..365, default 90'. The description restates the same facts without adding new meaning, so the baseline of 3 is appropriate.

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

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

States a specific verb (aggregate) and resource (risks), plus scope (caller's visible projects, by category). This clearly differentiates it from org-wide siblings like list_org_risk_patterns and per-project analyzes like analyze_project_risks.

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 visible projects' scope and the note that it drives the Critical Risk Register badge give clear context for when this applies. However, it never explicitly names an alternative tool or a when-not condition, leaving sibling selection 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 non-destructive, non-read-only. The description adds real context beyond them: the record is created in DRAFT state, membership is required, and the changeControl feature gate (ENTERPRISE+) will reject calls otherwise. It does not discuss the optional idempotency key or returned identifier, but the feature/reachability context is genuinely useful.

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

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

Three tight sentences, front-loaded with the action and state. The parenthetical type list is the only low-value filler since it duplicates the enum.

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?

Good on access constraints and lifecycle state, but for a 19-parameter mutation with no output schema, the agent gets no signal about what is returned (an ID?) or the natural next step (submit_change_request). Adequate but with clear gaps.

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

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

Schema coverage is only 42% across 19 parameters. The description's enumeration of change types merely restates the type enum, and it says nothing about the many undocumented fields (linkedRisks, rollbackPlan, justification, customerImpact, complianceNotes, approvalThreshold, budgetImpactAmount). With low coverage, the description should compensate and does not.

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 (create a DRAFT change request on a project) and the parenthetical names the change categories. The DRAFT qualifier usefully previews the create/submit split with siblings like submit_change_request, though it never names them 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?

States prerequisites (project membership, changeControl feature at ENTERPRISE+) and that the result is a draft, which implies a follow-up submission step. It never explicitly says when to use this instead of submit_change_request or list_change_requests, leaving routing 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?

Adds real context beyond the annotations: an authorization prerequisite ('Caller must have visibility into the parent project'), the default routing behavior (comments land in the team thread, including the agent's own status updates), and the directed-conversation pattern for replying. Annotations already cover the safe/non-destructive profile, so the remaining gap is minor.

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 what, then the routing rules, so the highest-value information is read first. The final sentence is long and parenthetical-heavy, but each clause carries a distinct rule rather than padding.

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

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

Covers parent selection, content formatting expectations, thread routing, and the visibility prerequisite for a 7-parameter create tool with no output schema. The only uncovered area, retry/idempotency semantics, is handled adequately by the schema's own parameter description.

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 baseline is 3, but the description goes further by explaining the operational intent behind threadKind ('[Agent] tab' vs '[Comments] tab') and by warning that the parameter applies to task comments only. The idempotencyKey parameter 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 ('Post a comment') and enumerates the four supported parent resources, with the exactly-one-parent constraint up front. An agent can immediately distinguish this from edit_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 explicit when-to-use ('AI-generated status updates, follow-ups, or notes - including progress on an Issue you filed') and a precise when/when-not for threadKind: default to the team thread, and set 'AGENT' ONLY when echoing a threadKind you read back from get_task/list_comments/list_related_tasks. It even names the read tools that supply that value.

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 declare the generic mutating profile (readOnly=false, idempotent=false, destructive=false); the description adds non-obvious behavior: the currency must be pre-converted to the project currency, and a SPENT line feeds the project's earned-value actual cost. It also states the exact permission requirement, which annotations do not cover.

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

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

Three tight sentences: purpose first, then the currency trap, then the EVM consequence and access rule. Every clause carries information the agent cannot get from the schema or annotations.

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

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

For an 8-parameter, non-idempotent create tool with 88% schema coverage and no output schema, the definition covers the risky unknowns: units, side effects on earned value, and authorization. Nothing important for a correct first call 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 already 88%, so the baseline is 3; the description adds real meaning on top by explaining the monetary unit of amount and the business meaning of the EXPECTED/COMMITTED/SPENT status values. The date parameter's earned-value effect is only in the schema, so the description does not fully duplicate the value.

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

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

States a specific verb and resource ("Add a cost line to a project's budget list") and immediately enumerates the three data dimensions it captures. An agent can tell this is the create-side of the cost-line family versus list_cost_lines or update_cost_line 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 clear preconditions in the form of a hard constraint ("There is no currency argument: convert the amount first") plus the authorization rule (project.edit and budget.read). It never names list_cost_lines or update_cost_line as alternatives, so there is no explicit when/when-not routing, 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 cover the safety profile (readOnly=false, destructive=false, idempotent=false), so the bar is lower, and the description adds real context the annotations lack: the PRO+ feature gate and the differing authorization rules for org-wide (admin/manager) vs project-scoped (project owner/manager) fields. It still omits return behavior and uniqueness constraints.

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 is front-loaded in the first clause and the remaining sentences are dense with constraints and no filler. Slightly enumeration-heavy, but every sentence carries operational information.

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

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

For a mutation tool with no output schema, the description covers the key domain constraints (tier, valid types, option requirement, scoping and authorization). It is nearly complete, missing only what happens on success or on a name collision.

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 75%, so the baseline is 3. The description largely restates what the schema already encodes — the fieldType/entityType enumerations and the option requirement for DROPDOWN/MULTI_SELECT — adding only the role implications of projectId rather than new syntax or format meaning.

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

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

States a specific verb ('Create') and resource ('custom field definition') and immediately scopes it with the PRO+ tier gate. It is unambiguous against siblings like update_custom_field_def, list_custom_field_defs, and set_custom_field_value.

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 selection guidance for the projectId parameter (omit for org-wide vs set to scope to one project) and ties each path to an allowed role. It does not explicitly name the sibling to use for editing or listing, so it falls short of full when/when-not routing.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent write; the description adds material context beyond them: the required auth scope, the positional side effect ('appended at the end of the project's epic order'), and the deprecation window for the 'name' alias. Auth requirements and ordering side effects are exactly the kind of behavior an agent cannot infer from the 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?

Front-loaded with purpose, then required fields, then optional fields, then side effect and permission — a logical order with no filler. It is dense but not padded, though the alias/deprecation detail is repeated verbatim from the schema and could be trimmed.

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

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

For a 6-param mutation tool with no output schema and full annotation coverage, the description supplies purpose, validation bounds, auth scope, ordering behavior, and deprecation timing. It does not say what the call returns (e.g. the new epic's id) or whether duplicate titles are permitted, which are minor residual gaps.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including the deprecated alias and idempotencyKey semantics. The description largely restates those constraints (title 2-200, description 5000, color hex/default indigo) rather than adding syntax the schema lacks, 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 ('Create an Epic on one project') and immediately defines the domain concept ('Epics group related tasks under a business theme'). This clearly separates it from create_task, create_project, and update_epic 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 scoping condition ('on one project'), the required inputs, and the prerequisite permission ('project.content.create, default project MEMBER+'), which tells the agent whether the call will succeed. It does not explicitly name update_epic as the alternative for modification or state when not to use it, 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 this is a non-read-only, non-idempotent, non-destructive write. The description adds genuinely new behavioral context beyond that: the Authorization requirement (org.governance.manage, Admin+ by default) and the licensing gate (ENTERPRISE+). It stops short of noting duplicate-name behavior or defaults, so not 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?

Three short sentences, front-loaded with the purpose, then permission, then feature gate. Every clause carries distinct information with no filler.

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

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

For an 8-parameter mutation tool with no output schema and 63% schema coverage, the description covers authorization and licensing well but omits how fields interact (e.g., options only apply to DROPDOWN, weight/maxScore constraints) and what is returned on creation. Adequate but with clear gaps.

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

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

Schema description coverage is only 63% across 8 parameters, and the description contributes no parameter meaning at all beyond the implied 'gate' target. Ambiguous fields like fieldType, weight, and options (which feed DROPDOWN/SCORE semantics) get no explanation in either the description or the partially-covered 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 (Create) and resource (org-specific evaluation criterion) scoped to a governance gate, which cleanly separates it from update_evaluation_criterion and list_evaluation_criteria. It does not name siblings explicitly, but the create/update/list distinction is unambiguous 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 prerequisites rather than selection guidance: it names the required permission (org.governance.manage, Admin+ default) and the ENTERPRISE+ governance feature. It never says when to create a criterion versus updating an existing one or how this relates to gate review workflows, so usage is only implied.

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

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

Annotations already declare this is a non-destructive, non-open-world, non-idempotent write, so the safety profile is covered. The description adds genuinely useful behavior: the caller becomes the owner, and parentId nests within an existing goal. However, it is silent on the `idempotencyKey` retry semantics that the schema documents (and the idempotentHint=false annotation arguably undersells), leaving a notable gap for a create 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?

Front-loaded with the core action, then the required field, then optionals, then the hand-off sibling — a logical order. Efficient overall, though 'title is required' duplicates the schema's own required declaration.

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 create tool with no output schema, it covers the required field, defaults, ownership, and the next-step sibling. It does not indicate what the call returns (e.g., the new goal id), which the agent needs to chain into create_key_result or update_goal, a minor but real 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 the schema already documents all 8 parameters including enums and the detailed idempotencyKey text. The description largely restates those fields (type default, parentId nesting, projectIds linking) rather than adding new syntax or format meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create a goal / objective / OKR in the caller's org') and explicitly names the sibling it hands off to for a related operation ('Use `create_key_result` to add measurable KRs'). An agent can distinguish it from the many other create_* tools without opening a schema.

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

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

Gives clear context for use (goals in the caller's org) and an explicit alternative for the follow-up step via create_key_result. It lacks any when-not guidance or prerequisites (e.g., feature/tier gating), so it stops short of the top score.

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 declare a non-destructive, non-read-only, non-idempotent write; the description adds genuinely new behavior: the idea is private to the capturing user until shared, never appears in anyone's task list, and visibility is changed in the web app. It also describes the return payload. It does not address duplicate/retry behavior implied by idempotentHint=false, 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?

Front-loads the core definition, then escalates to contrast with create_task, privacy, projectId guidance, and return shape. Every sentence carries information, though the paragraph is on the long side for a single create call.

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 supplies the return fields (id, idea with id/title/status, url), covers the privacy model, the optional-vs-required parameter split, and the promotion path. Nothing an agent needs to invoke 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 description coverage is 100%, so the schema already documents all five parameters including the 'omit for a General (unfiled) idea' wording. The description reinforces the projectId case and adds the reasoning behind it, but contributes little textual meaning beyond the structured fields; 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 ('Capture an IDEA') and immediately defines the resource's distinguishing nature: uncommitted, possibly half-formed, no assignee, no due date. It explicitly distinguishes itself from the sibling create_task, so an agent can route correctly 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?

Gives an explicit when-to-use rule ('use this instead of create_task when the thing is not agreed work yet'), names the alternative tool, and adds the follow-up path ('Promote it later with promote_idea'). projectId omission guidance ('normal case when someone is just thinking out loud') further disambiguates usage.

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 (not read-only, not destructive, not idempotent), so the burden is lighter. The description adds real behavioral context beyond that: the issue starts in OPEN status, and the return payload (id, issue object, url) is described. It doesn't mention permission requirements or duplicate-creation behavior, keeping it short of 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?

Information-dense with no filler and the key routing rule (use this not create_task) is front-loaded. The enum lists make it slightly list-heavy, but every sentence carries unique, useful 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 an 11-parameter mutation tool with no output schema, the description covers the critical optional-parameter semantics and describes the return shape itself. A few parameters (targetResolutionAt, ownerId, companyId, description) are left to the schema, which is reasonable given 82% coverage.

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

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

Schema coverage is 82%, so the schema already documents most parameters. The description adds meaning beyond the schema by spelling out the type and severity enums, the projectId omit-for-General semantics, and the optional risk/task/change-request linkage purpose. This meaningfully complements rather than repeats 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 (File) and resource (a new Issue) and anchors it to PMBOK Issue Log semantics as 'a problem that has already happened and needs triage'. It explicitly distinguishes itself from the sibling create_task, so an agent can route correctly 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?

Gives an explicit when-to-use and when-not: 'Use this - NOT create_task - for bugs, blockers, and materialized problems', plus a conditional rule for omitting projectId to file an org-level General issue. This is directly actionable 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds value the annotations don't: an authorization rule ('Any org member except a Guest may add one') and default behaviors for unit/startValue. It omits the idempotencyKey retry behavior that the schema describes, which is the one notable behavioral gap.

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

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

Three dense sentences: purpose, parameter contract, authorization. Required parameters and the one branching parameter are front-loaded; no sentence is padding.

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

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

For a 7-parameter mutation tool with no output schema, it covers the required inputs, defaults, enum usage, permissions, and the manual-vs-rollup fork. The only meaningful omission is any mention of the idempotencyKey retry contract, which the schema handles but the description ignores.

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 goes beyond the schema by restating required vs. optional grouping, the >0 constraint on targetValue, defaults for unit/startValue, and the enum values plus the semantic meaning of omitting rollupMethod (manual updates).

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

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

Specific verb+resource+parent: 'Attach a measurable Key Result to an existing goal.' An agent can immediately separate this from create_goal (creates the parent) and update_key_result_value (mutates an existing KR).

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 routes one decision explicitly: leave rollupMethod unset for manual updates via `update_key_result_value`, which names the sibling tool and the condition that selects it. It also states who may call it. It does not give broader when-to-use context vs. create_goal, but the create-vs-update boundary is implied clearly by 'existing goal'.

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 declare the mutation/safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=false), so the description's added context is genuinely valuable: required permissions per scope, the Viewer read-only caveat, MANAGER+ default for org libraries, and the guarantee that agent-created libraries are user-visible and never the system auto-stash variant.

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 action, then constraints, then permissions, then the visibility caveat — a sensible order with no filler. Slight deduction because the 'name is 1..200 chars' clause duplicates the schema's own description text, and the sentences are dense and multi-clause.

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 5-param mutation tool with no output schema, the description covers scope selection, validation bounds, authorization requirements, and the visibility semantics of the created object. Nothing an agent needs in order 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?

Schema coverage is only 40% (projectId, proposalId, and description are undocumented), but the description compensates fully: it names all three scope selectors, explains the 'exactly one' exclusivity rule, and restates the name length bound plus the optional description. An agent can construct a valid call from the description alone.

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 document library') and immediately enumerates the three mutually exclusive scoping modes, which cleanly separates it from create_project, create_proposal, and upload_library_document. It never explicitly names a sibling it is not, so differentiation is implicit 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?

Explicitly states the calling constraint ('Specify exactly one scope: projectId, proposalId, or scope="org"') and gives the per-scope permission prerequisites, so an agent knows the correct invocation shape. It stops short of when-not-to-use guidance or pointing at alternatives such as upload_library_document for existing libraries.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so safety is largely covered. The description adds a genuine behavioral fact not in the annotations: the required milestone.create permission on the target project. It omits return shape, but that is a minor gap against annotation coverage.

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

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

Two short sentences, zero filler, with the core action and its scope front-loaded before the permission caveat. Nothing here is redundant with the name or the 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 4-parameter mutation tool with no output schema, the description covers purpose and authorization but says nothing about what is returned (e.g., a milestone id) or duplicate/error behavior beyond what the schema's idempotencyKey note supplies. Adequate but with visible gaps.

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

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

Schema coverage is 75%, so most parameters carry their own descriptions (title length bounds, ISO date format, and a detailed idempotencyKey contract). The description only indirectly gestures at projectId via "on one project" and adds no semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description gives a specific verb+resource ("Create a milestone") plus scope ("on one project") and a semantic differentiator ("zero-duration marker for key dates") that separates it from sibling create_task or create_epic. An agent can tell what this tool produces 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 states a hard precondition (caller must hold milestone.create on the project), which tells the agent when the call will be permitted. However, it offers no guidance on when to prefer this over siblings like update_milestone, propose_milestone_completion, or list_milestones, and no exclusions or alternative routing.

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 non-read-only, non-destructive, non-idempotent profile, so the bar is lower. The description still adds real behavior: the file lands in the Documents tab and can be co-edited in the in-browser Office editor, and it requires the project.content.create permission (CONTRIBUTOR+, Viewers read-only). It does not touch duplicate-name or repeat-call behavior, so a 4 rather than 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?

The verb+resource is front-loaded, followed by the alternative-routing rule, format aliases, prerequisite, and permission note. Five dense sentences, each of which carries distinct information with no filler.

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

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

There is no output schema, yet the description still tells the agent what gets created, where it appears, how it will be edited, what permissions are needed, and which sibling to use instead. For a creation tool with three simple parameters, nothing an agent needs 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 the enum aliases and the name default are already documented, giving a baseline of 3. The description goes slightly beyond the schema by spelling out that libraryId must reference an existing library and how to obtain one via create_library, adding actionable meaning.

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

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

States a specific verb and resource ('Create a blank, editable Office document') and enumerates the three formats, so the agent knows exactly what is produced. It also distinguishes itself from the sibling draft_document by noting that the latter only makes markdown.

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 use this versus the alternative ('Use this (not draft_document...) when the deliverable should be a real Office file the team will edit'), and adds the prerequisite for libraryId ('create one first via create_library if needed'). Nothing about routing 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 non-read-only, non-idempotent, non-destructive. The description adds real value beyond them: PRO+ gating, server-side validation against a component allowlist and https-only url policy, the 'omit content to start empty' default, and the contribute-access 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-loads purpose, then scoping, then content rules, then permissions. Information-dense but each clause earns its place; only lightly long.

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

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

Given no output schema, the description still covers scoping, validation policy, permission prerequisites, and the empty-content default. An agent has enough to invoke correctly, though the return shape is unspecified.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces projectId scoping and content validation but largely restates what the schema already documents, adding only the 'omit it to start empty' behavioral note.

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

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

States a specific verb and resource ('Create a web part page') with the org-vs-project scope distinction made explicit. It does not, however, differentiate itself from the nearby create_wiki_page or create_whiteboard siblings, 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?

Gives clear routing guidance: omit projectId for an org page, pass it for a project page, and states the access requirement for each case. It stops short of naming alternative tools or when-not-to-use conditions.

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

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

Annotations already declare the mutation/safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the bar is lower. The description adds genuinely useful non-obvious behavior: the caller becomes owner, and the authorization prerequisite with a default role threshold.

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 compact sentence, front-loaded with the action and followed by the two facts an agent most needs (ownership outcome and permission). Zero filler.

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

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

For a simple two-param creation tool with no output schema, the description covers action, ownership side effect, tier, and authorization. Minor gaps (duplicate-name behavior, whether the new portfolio id is returned) are low-impact.

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% — both 'name' (min 2 chars) and optional 'description' are fully documented in the schema. The description adds no parameter syntax or format detail, so this is the baseline 3, not a penalty.

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 portfolio') and immediately distinguishes it from siblings like update_portfolio and list_portfolios. The parenthetical feature-tier note adds scope precision without ambiguity.

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 caller clear context: BUSINESS+ tier, required permission org.portfolio.manage with a default Manager+ role. It doesn't explicitly state when not to use it vs. update_portfolio or add_project_to_portfolio, 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 only declare the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false). The description adds non-obvious behavior: the caller becomes owner, default date range of today to ~90 days, STRATEGIC being refused in classifying orgs, and that the result carries nextSteps and a url. That is substantial disclosure beyond what the annotations provide.

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

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

Front-loads purpose and the key routing rule in the first two sentences, then layers prerequisites, side effects, and return-value handling. It is long, and a few clauses (e.g. restating the date default) echo the schema, but almost every sentence 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?

With no output schema, the description correctly describes the returned artifacts (`nextSteps`, `url`) and instructs the agent to surface the link. For a 10-parameter mutation tool it covers ownership, defaults, refusal cases, idempotency, and follow-on calls, leaving no critical 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 the baseline is 3 and the schema already documents defaults for startDate/endDate and the STRATEGIC enum. The description reinforces the date-default behavior ('adjustable later with update_project') and the STRATEGIC refusal, but does not add much syntax the schema lacks.

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

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

States a specific verb and resource ('Create a new, EMPTY project') and immediately qualifies scope ('a named container with an optional start and end date and no tasks yet'). The EMPTY emphasis plus explicit contrast with instantiate_plan lets an agent distinguish it from the sibling that also creates projects.

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

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

Gives concrete user phrasings for when to use it ('start a project called X') and when not to ('plan a website launch'), naming instantiate_plan as the alternative. It also warns about the specific failure mode (two projects, empty one left behind) and points to list_projects with `search` for duplicate checking.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent write, so the safety profile is covered. The description adds useful context the annotations lack: the created record starts in DRAFT and is intended to flow through an approval pipeline, plus an enterprise feature gate. It omits behavioral details such as permission requirements or side effects like notifications/reviews triggered.

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

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

Two tight sentences, front-loaded with the core action and no filler. The parenthetical '(DRAFT to APPROVED/REJECTED)' is compact but slightly ambiguous about whether this tool performs the transition or merely feeds it, which is the only structural blemish.

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 13-param creation tool with no output schema, the description covers purpose, initial state, and feature gating but omits what the call returns, required permissions beyond the feature tier, and how it relates to advance_proposal_stage/submit_proposal_review. Adequate but with clear gaps given the tool's complexity.

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 13 parameters and only 46% schema description coverage, the description carries a larger burden but contributes nothing about parameters — no mention of title, priority, riskLevel, sponsorId, or the idempotencyKey retry behavior documented in the schema. Several params are self-descriptive by name, which keeps this above 1, but the low coverage is not compensated.

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 DRAFT governance proposal') and pins the created object's initial lifecycle state, which distinguishes it from update_proposal and advance_proposal_stage. It does not name a sibling tool explicitly, so an agent must infer the boundary from the DRAFT-to-APPROVED lifecycle phrase.

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

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

The description implies when to use it (creating a new proposal for review) and adds a real prerequisite via the 'governance (ENTERPRISE+)' gate. It offers no explicit when-not or alternative routing (e.g., 'to modify an existing proposal use update_proposal', 'to move stages use advance_proposal_stage'), leaving usage context implied rather than stated.

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

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

Beyond the annotations (non-read-only, non-destructive, non-idempotent), the description discloses the write footprint ('creates one ProjectRisk row and never touches existing risks'), that analysis tooling will not mutate what is created here, and that the caller needs project write access. This is solid added context; it stops short of describing the response or duplicate-handling behavior, 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?

Dense but well ordered: what it records, the sibling exclusion, the side-effect profile, then the optional advanced fields. The main waste is the verbatim restatement of the two enum value lists, which already exist in the schema as structured data.

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

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

For an 8-parameter mutation tool with no output schema and no nested objects, the description supplies what a caller actually needs: write-access prerequisite, additive side effects, non-interference from analysis tools, and the meaning of the optional scheduling parameters. Nothing required 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?

Schema coverage is 75%, and the description adds real meaning on top: impactDays applies to EACH affected task, affectedTaskIds must be tasks in the same project, and probability/impactDays/affectedTaskIds are a coupled trio enabling the Monte Carlo run rather than three independent knobs. The severity and category values are restated from the schema enums, which is redundant.

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 ('Record a risk on a project's risk register') and immediately draws the boundary against the most confusable sibling: a risk is a 'might happen', while a problem that already happened belongs in create_issue. An agent can route correctly 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?

Gives an explicit when-to-use-this vs when-to-use-the-alternative rule (create_issue for realized problems) and clarifies the relationship to analyze_project_risks. It also names the downstream condition that makes the optional schedule fields worth supplying (the Monte Carlo schedule risk run).

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 significant context beyond annotations: it issues skip-and-continue semantics ('out-of-scope or missing tasks are skipped with reasons; the sprint is still created'), states the required permission (sprint.manage), and enforces a 50-task cap. Annotations already cover the destructive/read-only/idempotent profile, so this useful operational detail pushes it above baseline.

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

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

Three front-loaded sentences that lead with the atomic create-and-move purpose, then parameters, then failure/permission semantics. Dense and largely waste-free, though the parameter enumeration slightly repeats what the schema already carries.

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?