Onplana

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

The description adds behavioral context beyond annotations: required permission, active membership requirement, feature flag, and a security note about user content tags. However, it does not detail side effects or confirm no changes on idempotent retry.

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

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

The description is concise, front-loaded with the main action, and each sentence provides essential information. No wasted words.

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

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

For a simple idempotent mutation with one parameter and no output schema, the description covers purpose, permissions, preconditions, and security, making it complete for reliable use.

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 parameter is well-described in the schema. The description adds no additional meaning to the parameter beyond what the schema provides.

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

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

The description clearly states 'Add a user to the org-level Change Control Board,' specifying the verb and resource. It does not explicitly differentiate from sibling tools like add_project_member, but the 'org-level' qualifier helps distinguish.

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 mentions prerequisites (admin permission, active member) but does not provide guidance on when to use this tool versus alternatives.

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

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

Beyond annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds that it only works for existing org members, does not send emails, and includes a security note about user content handling. No contradictions with annotations.

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

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

Two concise paragraphs: first covers core usage, second is a security note. Front-loaded with key action, no redundant 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?

Covers essential aspects: prerequisites, permissions, exclusion, and security. Lacks return value information (e.g., success response), but given tool simplicity and annotations, it 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?

Description adds meaning for userId (look up with list_org_members) and role (lists enum values). However, projectId lacks context beyond the schema. Schema coverage is 33%, so description partially compensates but leaves one parameter underspecified.

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

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

The description clearly states the action ('Add an EXISTING active org member to a project'), specifies the target (project), and distinguishes from inviting new users by directing to the invitation UI. This differentiates it from siblings like add_ccb_member and update_member_role.

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

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

Explicit guidance: use list_org_members first to get userId, required permission (project.members.manage), and when not to use (invite new users via UI, as this tool does not send emails). Clear alternatives provided.

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

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

The description discloses important behavioral traits beyond annotations: it is idempotent-safe (returns error on duplicate), requires specific permission, and includes a security note about user content tags. No contradictions with annotations.

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

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

The description is concise: two sentences for core details, a note about behavior, and a security note. All sentences add value, and key information is front-loaded.

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

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

Given no output schema, the description covers purpose, permissions, and duplicate handling. Missing return value details, but for a simple add tool, it is largely complete.

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

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

The input schema has 100% coverage with descriptions for both parameters ('Id of the project to add' and 'Id of the portfolio'). The description adds no further detail about parameter format or source, so baseline 3 is appropriate.

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

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

The description clearly states the action: 'Add a project to a portfolio'. It specifies the feature tier (BUSINESS+), required permission, and idempotency behavior. Among siblings, no other tool adds a project to a portfolio, so it is well-differentiated.

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 mentions when to use the tool and the required permission (org.portfolio.manage). It does not mention when not to use or alternatives, but for a straightforward add operation, this is sufficient.

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 indicate this is a write operation (readOnlyHint=false) and not destructive. The description adds atomic behavior, rollback on failure, inheritance of project, and a security note about user content tags, going beyond annotations.

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

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

The description is concise, front-loaded with key facts, and includes a security note without redundancy. Every sentence adds value.

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

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

No output schema, but description mentions returns created ids. Covers limits, atomicity, alternative usage, and security. Lacks explicit return type details but sufficient for typical use.

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 detailed parameter descriptions. The description adds context like inheritance and limits, but these are already partially in the schema. No significant new parameter semantics beyond the schema.

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

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

The description clearly states it creates subtasks under a parent task atomically, returns ids, and has a limit of 25. It distinguishes itself from create_task by emphasizing atomicity and single transaction.

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 'Use this instead of calling create_task repeatedly when decomposing a claimed task' and highlights benefits like single transaction and atomic rollback. This provides clear when-to-use and when-not-to 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?

Beyond annotations (idempotentHint=true, destructiveHint=false), the description adds critical behavioral traits: requires OWNER/ADMIN, user must be active org member, feature requirement (timeTracking PRO+), and a security note about output handling. No contradiction with annotations.

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

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

The description is concise and front-loaded with essential information. The security note adds length but is relevant. Minor redundancy could be removed, but overall 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?

Despite lacking an output schema, the tool is simple and the description covers prerequisites, behavior, and security considerations. Complete for a straightforward mutation tool.

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

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

Schema coverage is 100% and the description does not add extra meaning to the 'userId' parameter beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states 'Add a user to the designated timesheet approver list' with specific verb and resource. It differentiates from siblings like 'add_ccb_member' and 'add_project_member' by specifying 'timesheet approver 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?

The description provides clear context for when to use the tool (add a timesheet approver) but does not explicitly state when not to use or mention alternatives. However, the context is sufficient for correct invocation.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds significant context: it skips workflow run and auto gate-approval on the agent path, lists role restrictions per action (owner+, reviewer+, gate-panel restricted), and includes a security note about user content tags. No contradictions with annotations.

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

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

The description is well-structured with a clear main sentence, a list of actions, and separate notes about workflow and security. Each sentence adds value, though it could be slightly more concise. Front-loaded with the primary purpose.

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

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

Given the tool has no output schema and only two parameters with an enum, the description covers the state transitions, role restrictions, and behavioral nuances well. It lacks details on return values or error cases, but for a mutate-and-return tool, it is reasonably 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 for parameters is 0%. The description does not explain 'proposalId' beyond being an identifier, and 'action' is fully defined by the enum. The main text describes actions but adds no new semantics for the parameters themselves. This is a gap given no schema descriptions.

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

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

The description clearly states the tool's purpose: 'Drive a governance proposal through its lifecycle.' It enumerates six specific actions with target state transitions, distinguishing it from related tools like 'update_proposal' or 'submit_proposal_review' which handle field edits or review submissions.

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

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

The description explains when to use the tool by detailing the state machine and actions. It notes that it 'skips workflow run + auto gate-approval seed on the agent path' and mentions 'Plan gate: governance,' providing context about workflow behavior. However, it does not explicitly list when not to use or compare to alternatives like 'update_proposal'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds useful behavioral context: it collapses multiple round-trips into one, includes a security note about user content tags, and specifies what data is returned. No contradictions.

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

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

The description is two paragraphs. The first is dense but well-structured and front-loaded with key information. The security note is relevant but adds length. Overall, it earns its place with no wasted 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?

Given zero parameters, no output schema, and the tool's role as an entry point, the description is complete. It explains the return data, the collapse of multiple endpoints, and provides post-use guidance, leaving no ambiguity about what the tool does or how to proceed.

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

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

The tool has zero parameters, so a baseline of 4 is appropriate. The description adds value by explaining what the tool returns, which compensates for the absence of an output schema.

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

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

The description clearly states the tool is a 'ONE-CALL cold start' that returns identity, capabilities summary, schema index, and assigned-task count. It explicitly distinguishes from siblings by naming whoami, describe_capabilities, describe_schema, and list_assigned_tasks.

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 says 'call this FIRST in a fresh session' and provides drill-in guidance with specific tool names ('Then drill in only as needed: describe_capabilities..., describe_schema..., list_assigned_tasks...'). It offers clear when and when-not instructions.

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

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

Annotations declare readOnlyHint: true, but the description claims results persist to the project risks table, implying a write operation. This is a clear contradiction. The description also includes a security note but does not resolve the inconsistency.

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 covering purpose, usage, and security. Efficient and front-loaded, but the security note is necessary and adds value. No unnecessary content.

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

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

Covers purpose, usage, and a prerequisite, but lacks output description (no output schema) and the persistence claim conflicts with annotations. Adequate but incomplete given the contradiction.

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 0% schema description coverage, the description should compensate but only implicitly refers to projectId via 'one project'. It adds no additional meaning or format details for the single parameter.

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

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

The description clearly states the tool runs AI risk analysis on a single project, with specific usage examples ('what could go wrong on Project X', before sprint planning). It distinguishes itself from sibling risk tools like auto_detect_import_risks and compute_risk_patterns.

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 explicit when-to-use scenarios and a prerequisite (visibility into the project). However, does not mention when not to use or compare to alternative risk tools among siblings.

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?

Describes append-only nature ('No undo'), idempotencyKey behavior, and security note. Annotations show readOnlyHint=false and destructiveHint=false, which aligns with write operation. However, idempotentHint=false contradicts the described idempotency via key, but description clarifies it.

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

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

Two paragraphs: first covers tool purpose and parameters, second security note. Every sentence adds value. Could be slightly more concise but acceptable.

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 purpose, all parameters, behavior (append-only, idempotency), security. No output schema, but description hints at results via 'replays original result'. Minor gap: does not specify return value format explicitly.

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 descriptions. Description adds context: conversationId is the session, lineNum monotonic, level <=8 chars, text <=4000 chars, taskId triggers UI broadcast. Adds value beyond 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?

Description starts with 'Append a streaming progress log line to the current agent conversation.' Clearly states verb (append) and resource (log line) and distinguishes it from sibling tools which are all different.

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?

Lists required and optional parameters with explanation of when taskId is useful. Implicitly clear this is the only logging tool. Does not explicitly state when not to use, but that is not needed.

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

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

Annotations already provide idempotentHint and destructiveHint; description adds eligibility, feature requirement, and a security note about user content tags, adding useful context.

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

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

Two concise sentences plus a security note; front-loaded with main action, no unnecessary content.

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

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

Adequate for a simple tool with one parameter and no output schema; eligibility and feature info provided, but lacks description of return value or error cases.

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

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

Only one parameter (entryId) with 0% schema coverage; the description does not explain the parameter format or source, but the purpose makes it obvious.

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

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

The description clearly states the tool approves a single submitted timesheet entry and specifies eligibility conditions, distinguishing it from sibling tools like reject_timesheet_entry or approve_timesheet_week.

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?

Describes when to use (approve a single entry) and eligibility, but does not explicitly contrast with alternatives like approve_timesheet_week for weekly approval.

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

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

The description discloses that the operation is a mutation ('bulk-approve'), which aligns with the destructiveHint annotation. It additionally provides the eligibility requirement and includes a security note about user content handling in results. This adds valuable context beyond annotations.

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

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

The description is concise: two sentences covering core purpose and prerequisites, plus a security note. Every sentence adds unique value, and the core action is front-loaded. No wasted words.

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

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

For a simple tool with 2 parameters and no output schema, the description covers purpose, prerequisites, feature requirement, and security. It is complete and leaves no obvious 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?

Both parameters are described in the schema (100% coverage), so baseline is 3. The description adds the specific formatting guidance for weekStart ('Monday date (YYYY-MM-DD)'), which is useful. No additional semantics for userId beyond the schema.

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

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

The description clearly states the action (bulk-approve), the resource (all SUBMITTED timesheet entries), and the scope (specific user, given week). It distinguishes itself from siblings like 'approve_timesheet_entry' and 'reject_timesheet_week' through the 'bulk' and 'week' qualifiers.

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 states the prerequisite: 'Caller must be an eligible approver.' It also mentions the feature requirement: 'timeTracking (PRO+).' While it doesn't explicitly list when not to use or directly compare to siblings, the bulk vs. single distinction is clear from the name and context.

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

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

Annotations indicate mutation (readOnlyHint=false) but not destructive; description confirms assignment. Includes a security note about user_content tags, adding transparency beyond annotations.

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

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

Two tightly written sentences plus a security note; no wasted words. Information is front-loaded and each sentence serves a clear purpose.

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

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

Covers purpose, constraints, access, and security. Without an output schema, the description adequately informs the agent about behavior and requirements.

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 each parameter described. The description adds the crucial mutual exclusivity rule not present in individual parameter descriptions, enhancing semantics.

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

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

The description clearly states the action ('Assign a tag') and the target entities ('task or project'), distinguishing it from siblings like 'create_tag' and 'unassign_tag'.

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 specifies mutual exclusivity of taskId and projectId, and notes access requirement. Does not explicitly contrast with other tag-related tools but provides sufficient context for proper use.

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: permission needed, optimistic concurrency behavior (CONFLICT), dryRun preview, return of claimRevision, and security note about user content tags. No contradictions with annotations.

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

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

Well-structured with main action upfront. Each sentence adds value, though some points could be merged. Security note is relevant but appended. Efficient overall.

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 permissions, error cases (CONFLICT, 404), and return values. Missing details on mutual exclusivity error handling and any limits/rate limits, but mostly complete for a complex mutation tool.

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

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

Schema coverage is 100%, but description adds value by explaining assigneeEmail resolution, 404 for non-members, expectedAssigneeRevision as optimistic guard, and dryRun's preview effect. Slightly above baseline.

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

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

The description clearly states 'Assign or unassign one task' with specific methods (assigneeId or assigneeEmail) and revision guard. It implicitly distinguishes from siblings like 'bulk_assign' by focusing on a single task.

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

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

Provides context for using assigneeEmail as alternative and mentions permission requirement, but lacks explicit when-not-to-use guidance or direct comparison to siblings like 'bulk_assign' or 'propose_assignment'.

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 and destructiveHint=false. The description adds behavioral details: creates a metadata row (not actual content), requires project.content.create permission, and includes a security note about free-text fields wrapped in security tags. No contradictions with annotations.

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

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

Two compact paragraphs with front-loaded main action. Every sentence adds essential information (purpose, constraints, permissions, security). No wasted words.

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

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

No output schema exists; description does not explain return values or response format. It covers purpose, constraints, and permissions but leaves the agent unsure what to expect after a successful call. Moderate completeness for a create tool.

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

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

Schema description coverage is 50%. Description adds value by listing all provider enum values and specifying url format (http(s) only). However, it repeats some schema info and does not explain libraryId beyond being required. 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?

Clearly states the tool attaches an external URL as a WorkspaceDocument, distinguishing it from file uploads (e.g., 'Zero bytes, just a metadata row') and from sibling tools like attach_sharepoint_document. Verb 'attach' plus resource 'external URL as WorkspaceDocument' is specific.

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 when to use (attaching external URLs), lists provider enum values, url format, and required permission. Does not explicitly exclude alternatives but provides sufficient context for decision-making.

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

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

Beyond annotations (which indicate a write operation), the description clarifies that no file is downloaded or copied, and includes a security note about user content wrapping. This adds valuable behavioral context not present in annotations.

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

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

The description is concise with two paragraphs. The first paragraph covers the core functionality and security stance, while the second adds a necessary security note. No superfluous information.

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

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

For a simple attach operation, the description covers key aspects (action, permissions, security), but lacks details on error conditions, idempotency, or what happens if resources are missing. Considering no output schema, it is moderately complete.

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

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

Schema description coverage is 0%, so the description must compensate. However, it does not explain the meaning of parameters like siteId, libraryId, projectId, or driveItemId. Only the need for read access to the SharePoint site is implied.

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

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

The description clearly states the tool's purpose: attach a SharePoint document as a LINK reference. It specifies the resource (SharePoint document) and the action (attach), and distinguishes it from general link attachment by emphasizing the link-only nature.

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 includes a prerequisite (caller must have read access) and implicitly guides usage for SharePoint documents vs. other attachment tools like attach_link. However, it does not explicitly say when not to use or list alternative tools.

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

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

Annotations declare readOnlyHint, destructiveHint, and idempotentHint. The description adds a cap of 100 values per dimension and a security note about user-content wrapping, providing behavioral context beyond annotations without 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?

The first paragraph is concise and front-loaded. The security note is important but adds length; overall well-organized and clear.

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 zero parameters, rich annotations, and no output schema, the description covers purpose, usage, behavioral constraints (cap, security), and prerequisites completely. No gaps identified.

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

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

No parameters exist, so schema coverage is 100%. Description appropriately adds no parameter info. Baseline is 4 for zero-parameter tools.

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 explicitly states the tool returns distinct action and resource values with row counts, and specifies its use for building filter chips before list_audit_log. This clearly differentiates it from sibling tools like list_audit_log.

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 when to use (before list_audit_log) and prerequisites (OWNER or ADMIN + auditLogs feature), providing clear context. No explicit alternatives or exclusions, but sufficient for the tool's simple role.

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

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

Beyond annotations, description explains idempotency mechanism ('dedupe — re-running does not pile up duplicates'), return behavior ('Returns the count of NEW risks inserted'), and important behaviors ('No LLM call, no plan gate'). Also includes a security note about user content tags, adding valuable context.

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

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

Description is well-structured: purpose first, then specifics, usage guidance, and security note. It is concise and front-loaded, with each sentence adding value. Slightly longer due to security note but still efficient.

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

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

Given the single parameter, full schema coverage, no output schema, and existing annotations, the description covers purpose, usage, behavioral details, and security. It is complete enough for an AI to correctly select and invoke the tool.

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

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

Schema description coverage is 100% with one parameter 'projectId' having a clear description. The description adds no further parameter semantics, so baseline 3 is appropriate.

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

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

The description clearly states the tool runs deterministic schedule-risk detection on a project and persists findings to the Risks tab. It lists specific risk types detected (project-end overruns, overdue tasks, etc.), distinguishing it from siblings like 'analyze_project_risks' or 'list_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?

Description explicitly recommends usage after import or when Risks tab is empty with a user query like 'are there any obvious problems?'. It notes idempotency via dedupe but does not explicitly state when not to use, though context is clear enough.

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

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

Discloses return structure (updated, skipped, errors), dryRun behavior, side-effect description, and security note about user content tags, all beyond annotation 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?

Concise yet comprehensive; every sentence adds value, structured logically from purpose to constraints and security.

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 return format, limits, error cases, permissions, and alternatives despite absence of output schema, making it fully actionable.

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?

Adds value beyond the 100% schema coverage by clarifying mutual exclusivity of assigneeId/assigneeEmail, meaning of null, and dryRun preview behavior.

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

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

The description clearly states the tool's purpose as (un)assigning multiple tasks to one person in a single call, distinct from the single-task assign_tool mentioned for optimistic concurrency.

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 guidance on when to use this tool vs. assign_task (for optimistic concurrency), and prerequisite requirements (permission, active member, max 200 tasks).

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 destructiveHint=false and readOnlyHint=false, but the description adds important behavioral details: single transaction (all-or-nothing) and a security note about user content tags. Could mention idempotency behavior beyond the parameter description.

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?

Concise, with key information front-loaded: purpose, usage guidance, and a separate security note. Every sentence adds value. Could be slightly more compact but effective.

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 main use case, sibling differentiation, constraints (up to 50), idempotency key behavior, and security. Lacks mention of return value, but output schema is absent. Adequate for the 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?

Schema coverage is 100%, so parameters are fully documented. The description adds a helpful summary for the 'tasks' array, restating constraints and optional fields. Does not significantly elaborate on other parameters.

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

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

Clearly states creating up to 50 sibling tasks in one call, specifying location options (project root, sprint, epic) and transactional all-or-nothing behavior. Effectively distinguishes from siblings: alternatives create_task and add_subtasks are explicitly mentioned.

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

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

Explicitly tells when to use this tool ('add these 10 tasks') versus create_task (multiple calls) and add_subtasks (child tasks). Provides clear context for appropriate 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 only indicate destructive and non-readonly. Description adds: partial success observable, skip vs error behavior, rollup trigger once per batch, and a security note about user content wrapping. Adds significant value beyond 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?

First paragraph is concise and informative. Security note is essential but adds length. Overall well-structured and front-loaded with key 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?

Covers purpose, usage, limitations, behavior, and security. Missing explicit mention of output format details (updated, skipped, errors) but those are given. Adequate for a bulk operation without output schema.

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

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

Schema coverage is 100%, so baseline is 3. Description does not elaborate on parameters beyond what schema provides; dryRun not mentioned. No extra semantic value added.

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

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

The description clearly states the tool flips status on multiple tasks in one call, distinguishing it from update_task by explicit use cases (marking siblings DONE, blocking a batch, reopening a set). Verb and resource are specific.

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 'Use this instead of N update_task calls when ...' providing clear when-to-use context. Also describes limitations (up to 50 IDs) and behavior for unauthorized tasks.

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

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

Beyond annotations (idempotentHint=true, destructiveHint=true), the description reveals partial failure behavior ('errors' reported without aborting) and dryRun preview mode. It adds value but does not exhaustively describe all side effects (e.g., notifications). No contradiction with annotations.

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

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

The description is concise and well-structured: starts with purpose, lists parameters, notes failure mode, permission, alternative, and security warning. Every sentence earns its place; no fluff.

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

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

Given the tool's complexity (5 params, no output schema), the description covers purpose, all parameters, failure behavior, permissions, and alternatives. It lacks details on the full return structure but mentions 'errors'. Adequately complete for selection and invocation.

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

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

The description adds meaning for parameters that lack schema descriptions: status and priority enums are listed with values, and shiftDueDateDays is explained. For parameters with schema descriptions (dryRun, taskIds), it reinforces but doesn't add new info. Schema coverage is 60%, so description compensates for missing param details.

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 explicitly states 'Apply the same partial update to many tasks at once,' clearly identifying the verb, resource, and scope. It distinguishes from sibling tool bulk_update_status by preferring that when only changing status, providing 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 provides explicit guidance: when to prefer an alternative (bulk_update_status for status-only changes), cites cost and atomicity benefits, and states the required permission (task.edit.any on each task's project). This fully informs the agent on when and how to use the tool.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds what metrics are returned, conditional output (revenue currency), and a security note about user content tags. No contradictions.

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

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

Description is concise but includes multiple sections (purpose, metrics, preference, access, security). Security note is somewhat lengthy but important. Front-loaded with core purpose.

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

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

Given no output schema, description lists metrics returned. Covers access, plan gate, and alternative. Missing error conditions or edge cases, but adequate for typical use.

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 has description, projectId does not). Description adds 'as of a given date (default: now)' for asOf, but projectId is only implicitly referenced ('for one project'). Does not fully compensate for missing schema descriptions.

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

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

Description clearly states it computes an EVM report for one project as of a date, lists specific metrics (BAC, EV, PV, etc.), and distinguishes from sibling calculate_evm_history by noting it's for time-series. Specific verb 'Compute' and resource 'EVM metrics'.

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 'PREFER calculate_evm_history for time-series,' guiding when to use alternative. Mentions access requirements (project member or admin) and plan gate (aiAdvanced). However, it does not explicitly state when not to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds security note about <onplana_user_content> tags and mentions 'same access + plan gate as calculate_evm', providing extra behavioral context.

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

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

Three sentences plus a security note. All information is front-loaded: purpose, metrics, usage context, access, and security. No wasted words.

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

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

For a simple read-only time-series tool with one parameter and no output schema, the description covers purpose, metrics, use case, access requirements, and security concerns comprehensively.

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

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

Schema has one required param (projectId) with 0% description coverage. The description mentions 'for one project' implying the parameter, but does not describe its syntax or type beyond what the schema provides. Adequate for a single obvious 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?

Clearly states 'Weekly EVM time-series for one project' and lists the specific metrics included (EV, PV, AC, CPI, SPI, EAC). Distinguishes from sibling calculate_evm by indicating it's a time-series, not a single point.

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?

Specifies it powers S-Curve and trajectory analyses, and references same access as calculate_evm. Does not explicitly state when not to use it, but the context is clear.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. Description adds behavioral context: prerequisite (manage workflow), feature tier, and a security note about user content wrappers in results. No contradiction.

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

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

Description is extremely concise: two sentences plus a security note. First sentence states purpose, second adds constraints, and third provides security context. No wasted words.

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

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

For a simple one-parameter action, description covers all essential aspects: action, prerequisite, feature restriction, and result handling note. Missing output details but no output schema exists; still sufficient for agent to invoke correctly.

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

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

Schema coverage is 100% with parameter 'runId' described as 'ID of the workflow run to cancel.' Description does not add further meaning beyond schema, so baseline score of 3 applies.

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

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

Description clearly states 'Cancel an in-progress workflow run' with a specific verb and resource. It distinguishes from siblings like list_workflow_runs by specifying 'in-progress' and no other tool cancels workflow runs.

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 prerequisite ('Caller must be able to manage the workflow') and feature tier ('Feature: automations (PRO+)'), but lacks explicit guidance on when to use versus alternatives. Since no similar cancel tools exist, minimal guidance is acceptable but not optimal.

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

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

The description adds a security note about user content tags, but beyond that it doesn't disclose behavioral traits like side effects, reversibility, or what happens on multiple captures. Annotations are present but not contradicted; the description offers moderate 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?

The description is concise with two main sentences and a separate security note. It is front-loaded with the purpose, then usage requirement, and ends with important security context. No unnecessary words.

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

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

Given no output schema, the description omits what the tool returns (e.g., baseline ID or confirmation). It mentions what is captured but not in exhaustive detail. For a tool of moderate complexity, it is adequate but not fully comprehensive.

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

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

The schema covers 2 parameters with 50% description coverage. The description adds meaning for the 'name' parameter (label and default) and implicitly clarifies 'projectId' through the tool's purpose, but the schema's missing description for projectId is not fully 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?

The description clearly states the tool captures a point-in-time baseline snapshot of a project, listing specific elements (tasks, dates, progress, EVM). This specific verb and resource distinguishes it from siblings like get_baseline and list_baselines.

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 specifies that the caller must be a project Owner or Manager, providing a clear role requirement. It also mentions the feature is for PRO+ tiers, giving context on availability, though it doesn't explicitly list alternatives when not to use.

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 provide readOnlyHint=false and destructiveHint=false. The description adds that the draft event lands in the user's calendar (non-destructive write), uses Calendars.ReadWrite scope, and has an external attendee cap. The security note about user content tags adds further transparency. No contradiction with annotations.

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

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

Two paragraphs with clear front-loading of the core action and constraint. Every sentence adds value, including the security note. No redundant information.

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

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

No output schema. The description covers purpose, constraints, and security, but does not explain what the tool returns (e.g., the draft event details) or error scenarios. Given the complexity of calendar invites, this gap affects completeness.

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

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

Schema description coverage is low (25%). The description lists the parameters in context but does not add detailed semantics beyond schema (e.g., format of attendees, that body can be HTML or text is covered by bodyContentType enum). It provides general context but not per-parameter enrichment.

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

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

The description clearly states it composes a draft meeting invite in the user's calendar, and explicitly notes it is preview-only (user must send manually). This distinguishes it from siblings like send_outlook_message and list_calendar_events.

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 (preview-only, not for sending) and mentions external attendee cap. However, it does not explicitly compare to other meeting tools or state when not to use it.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds scoping (caller's visible projects), return structure details, and a security note about user content tags, all of which go 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?

The description is concise: three sentences plus a security note. It efficiently covers purpose, output, usage context, parameter details, and a security warning. No extraneous content.

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

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

Despite lacking an output schema, the description adequately describes the return structure and result format per category. The parameter is fully explained, and the security note addresses potential data handling concerns. The tool is simple with one parameter, and the description covers all necessary context.

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

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

Schema coverage is 100%, but the description adds context: windowDays is optional (1..365, default 90) and bounds the detection lookback. This clarifies the parameter's purpose and constraints beyond the schema's description.

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

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

The description clearly states the tool aggregates risks by category across visible projects, specifies returned fields (acceptedCount, dismissedCount, affectedProjects, verdict), and links to a specific badge use. It is distinct from siblings like list_org_risk_patterns (lists all patterns) and analyze_project_risks (single project analysis).

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?

While the description implies usage for obtaining aggregated pattern data for the risk register badge, it does not explicitly state when to use this tool versus alternatives or provide any exclusion criteria. No guidance on when not to use it.

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

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

Annotations provide minimal behavioral info (readOnlyHint=false, destructiveHint=false). The description adds a security note about user content tags but does not disclose idempotency, rate limits, side effects, or permission details beyond membership. The idempotencyKey parameter suggests idempotency support, but the description does not mention it. Given low annotation coverage, the description should compensate but does not.

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

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

The description is concise: two sentences plus a security note. The first sentence is front-loaded with the core purpose. The security note, while valuable, adds length but is justified. No wasted words, though it could be slightly more 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?

Given 17 parameters, no output schema, and minimal annotations, the description is incomplete. It does not cover the lifecycle of the change request (e.g., what DRAFT means, how to submit later), nor does it explain most parameters. The security note is the only extra context. For a complex tool, more behavioral and flow context is needed.

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 35%. The description only implies the 'type' parameter via the mentioned change types (scope, schedule, etc.) and projectId indirectly. It does not explain required parameters like title or description, nor the many optional parameters. For a tool with 17 parameters and low schema coverage, the description fails to add meaning beyond the schema.

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

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

The description clearly states the action (create), the resource (change request), the state (DRAFT), the context (on a project with types: scope, schedule, budget, resource, other), and prerequisites (project membership, enterprise feature). It distinguishes from siblings like submit_change_request or implement_change_request by specifying 'DRAFT'.

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 provides clear context for when to use the tool (creating a draft change request) and prerequisites (project membership, enterprise feature). It does not explicitly exclude alternatives or state when not to use it, but the purpose implicitly guides the agent away from other related tools.

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

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

Annotations indicate write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds behavioral context: security note about user content tags, and the prerequisite for visibility. It does not contradict annotations.

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

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

The description is concise (two brief paragraphs plus a security note), front-loaded with purpose, and every sentence adds value. No wasted words.

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

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

Given 5 parameters, no output schema, and annotations, the description covers purpose, usage context, requirements, and security. It is complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add meaning beyond schema descriptions; the 'exactly one parent' constraint is already in param descriptions. The idempotencyKey behavior is documented in schema, not description.

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

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

The description clearly states the tool posts a comment on a task, project, or issue, with the constraint 'exactly one parent'. It distinguishes from siblings like 'edit_comment' and 'list_comments' by emphasizing creation on three parent types.

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 provides context for when to use the tool ('AI-generated status updates, follow-ups, or notes') and a prerequisite ('visibility into the parent project'). However, it does not explicitly compare to alternatives or state when not to use it.

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

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

Annotations indicate readOnlyHint and destructiveHint false, and the description adds a security note about user content tags and permission requirements (admin/manager for org-wide, project owner/manager for scoped). This adds context beyond annotations.

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

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

The description is fairly concise for the complexity but could be tightened slightly. It is well-structured with separate lines for key points and security note.

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

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

Despite no output schema, the description covers all key aspects: field types, entity types, required options for certain types, projectId scoping, permissions, and a security note. It is fully adequate for an 8-parameter tool.

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

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

Schema coverage is 75%. Description adds meaning by listing fieldType and entityType enum values, explaining options requirement, projectId scoping, and mention of default value. Not all parameters (e.g., 'required', 'description') get extra detail beyond schema.

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

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

The description clearly states the action 'Create a custom field definition', specifies it is a PRO+ feature, and lists field types and entity types, distinguishing it from sibling tools like update_custom_field_def and list_custom_field_defs.

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 guidance on when to use parameters (e.g., omit projectId for org-wide, set for scoped) and prerequisites (DROPDOWN/MULTI_SELECT require options). However, does not explicitly contrast with alternatives like update_custom_field_def.

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

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

The description adds significant behavioral context beyond annotations: it explains that the new epic is appended at the end of the project's epic order, details the idempotencyKey parameter for safe retries, and specifies permission defaults. The security note is also helpful.

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

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

The description is concise yet complete, with a clear front-loaded purpose statement followed by logically ordered details (required fields, optional, ordering, permissions, security). Every sentence adds value.

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

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

The description covers purpose, parameters, behavior, and permissions. However, it does not mention the return value (e.g., the created epic object), which is a minor gap given no output schema. Otherwise complete for a creation tool.

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

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

Schema coverage is 100% with descriptions, but the description adds extra meaning: title length constraints, deprecated status of 'name', description max length, color default, and idempotencyKey explanation. This enriches the parameter semantics beyond the schema.

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

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

The description clearly states 'Create an Epic on one project' and explains that epics group related tasks under a business theme. It distinguishes from sibling creation tools by specifying the target (epic) and scope (one project).

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

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

The description lists required fields (projectId, title) and optional fields, and specifies permission requirements ('caller must have project.content.create'). However, it does not explicitly contrast with other creation tools like create_task or create_goal, leaving some implicit inference needed.

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 are minimal (readOnlyHint=false, destructiveHint=false). The description adds value by disclosing the required permission, feature level, and a security note about user-content wrapping. This goes beyond annotations.

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

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

The description is very concise: three sentences that cover purpose, requirements, and a security note. No unnecessary words, and critical information is front-loaded.

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

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

The description covers purpose, permissions, and security, but omits what the tool returns (e.g., ID of created criterion). Given the complexity (8 parameters), the lack of return info and explanation of terms like 'governance gate' leaves some 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 63%, which is moderate. The tool description does not add any additional meaning to the parameters beyond what the schema already provides. Therefore, it meets the baseline but does not exceed it.

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

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

The description clearly states the action ('Create'), the resource ('org-specific evaluation criterion'), and the context ('for a governance gate'). This distinguishes it from siblings like 'update_evaluation_criterion' and 'list_evaluation_criteria'.

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 mentions required permissions and feature license, providing clear context for when to use. However, it does not explicitly state when not to use or compare with alternatives like updating an existing criterion.

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 provide basic flags (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds behavioral context such as 'Caller becomes the owner' and a security note about user content tags, which adds value beyond annotations.

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

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

The description is concise with two sentences in the main paragraph plus a necessary security note. It front-loads the purpose and presents parameters in a clear list, with no wasted words.

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

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

The description covers the tool's purpose, parameters, ownership, and a sibling alternative. It lacks an explicit mention of the return format, but for a create tool with no output schema, this is acceptable. The security note adds important context.

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 100% schema coverage, baseline is 3. The description adds meaning beyond the schema by explaining nesting for `parentId`, linking for `projectIds`, and default values for `type`. It also clarifies that `title` is required.

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

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

The description clearly states 'Create a goal / objective / OKR' using a specific verb and resource. It distinguishes from the sibling tool `create_key_result` by mentioning that tool for measurable KRs, providing clear 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 explicitly mentions an alternative tool (`create_key_result`) for adding measurable key results, guiding when to use this tool. However, it does not cover when not to use it or other 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?

Annotations indicate this is a non-destructive write operation. The description adds behavioral context: 'Starts in OPEN' and mentions optional linking of risks, tasks, or change requests. It also includes a security note about user-content tags, which is beyond what 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?

The description is two concise paragraphs with no fluff. The first paragraph covers the core purpose and usage, and the second adds necessary security context. Every sentence is informative and earns its place.

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

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

Given the tool has 10 parameters (4 required), 80% schema coverage, and no output schema, the description adequately covers the tool's behavior and parameter intent. The security note adds completeness. However, the lack of output schema description is not a gap since it is optional.

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 80% (8 of 10 parameters have descriptions). The description adds context for optional parameters like linkedRiskId, linkedTaskId, and linkedCrId by mentioning 'link a materializing risk, a fix-task, or a change request'. This adds value beyond the schema descriptions.

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

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

The description clearly states the verb 'File a new project Issue' and specifies the PMBOK Issue Log context. It explicitly distinguishes this tool from create_task, stating it is for 'bugs, blockers, and materialized problems'. The purpose is very specific and unambiguous.

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

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

The description provides clear guidance: 'Use this — NOT create_task — for bugs, blockers, and materialized problems'. It distinguishes this tool from a similar sibling (create_task). However, it does not explicitly mention when not to use it, such as for existing issues (which would use update_issue).

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 indicate this is a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). Description adds permission context and a security note about user content tags. No elaboration on side effects or idempotency beyond schema, but no contradictions.

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

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

Two short paragraphs: first covers purpose and parameters concisely, second provides a necessary security note. Front-loaded with required info, no extraneous text.

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

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

Covers purpose, parameters, permissions, security, and alternative tool. Lacks mention of return value/response format, but given no output schema, the description could be slightly more complete. Still, provides adequate context for a create tool with well-documented 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 baseline is 3. Description adds value by specifying constraints (targetValue > 0), defaults (unit default '%', startValue default 0), and the meaning of rollupMethod options with guidance to use update_key_result_value for manual updates. Increases clarity beyond schema descriptions.

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

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

Clearly states the action (attach a Key Result) and the resource (measurable Key Result to an existing goal). The description distinguishes this from siblings like create_goal and update_key_result_value by specifying it's a creation under a goal.

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 lists required and optional parameters, and mentions alternative tool (update_key_result_value) for manual updates when rollupMethod is omitted. Also states permission requirements. No explicit 'when not to use', but implied by alternatives.

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

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

The description adds behavioral context beyond annotations, such as 'Agent-created libraries are always user-visible, never the system's auto-stash variant' and the security note about user_content tags. Annotations confirm write operation, and there is no contradiction.

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

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

The description is concise with two short paragraphs, front-loading key usage info and appending a necessary security note. It avoids unnecessary 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?

The description covers purpose, parameters, permissions, visibility, and security, but does not specify the return value or expected response, which is notable given the absence of an output schema.

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

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

With only 25% schema description coverage, the description compensates by clarifying the mutual exclusivity of projectId and proposalId and noting name length and optional description, adding value beyond the schema.

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

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

The description clearly states 'Create a project (or proposal) document library' with a specific verb and resource. It also specifies the mutual exclusivity of projectId and proposalId, distinguishing it from any sibling create tools.

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

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

The description explains parameter constraints ('Specify exactly one of projectId or proposalId') and permission requirements ('Requires project.content.create'), but does not explicitly compare to sibling tools or provide 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?

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description adds a security note about user content tags. However, it does not disclose other behaviors like notification side effects or idempotency, which is partially covered in the schema but not in the description.

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

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

The description is very concise: two sentences plus a targeted security note. It is front-loaded with the main purpose and immediately useful information. Every sentence earns its place.

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

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

Given the simplicity of the tool (4 params, no output schema, annotations present), the description is fairly complete. It includes permission requirement and security warning. Missing details about idempotency behavior or error states, but overall adequate.

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

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

Schema description coverage is 75% (3 of 4 parameters have descriptions). The description does not add extra meaning to parameters; it only mentions 'zero-duration marker' which is not parameter-specific. Baseline 3 is appropriate given high coverage.

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

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

The description clearly states 'Create a milestone on one project (zero-duration marker for key dates)', specifying the action, resource, and nature of a milestone. It distinguishes from sibling tools like update_milestone or list_milestones.

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 includes a prerequisite: 'Caller must have milestone.create on the project.' This guides when to use the tool. However, it does not explicitly compare to similar tools (e.g., create_task) or state when not to use it.

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

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

Beyond annotations, the description adds that 'The caller becomes the portfolio owner' and includes a security note about user content tags. No contradiction with annotations.

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

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

The description is concise with two main sentences and a security note, front-loading the essential purpose without unnecessary 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 creation tool with 2 parameters and no output schema, the description covers ownership, permissions, feature restriction, and security, which is sufficiently 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 description does not add significant meaning beyond the schema. The description only restates what is in the schema without adding new semantics.

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

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

The description clearly states the action 'Create a portfolio' with additional context such as 'BUSINESS+ feature', 'caller becomes owner', and required permission, distinguishing it from sibling tools like update_portfolio.

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 provides explicit context for when to use (creating a portfolio) and mentions a prerequisite permission ('Requires org.portfolio.manage'). However, it does not explicitly state alternatives or when not to use.

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 value beyond annotations by stating caller becomes owner, idempotencyKey behavior (org-scoped, 24h replay), and the security note about user-content tags. Annotations only indicate it's not read-only/not idempotent; description fills in key behavioral details.

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?

Very concise: four sentences including a security note, all essential. Front-loaded with main action, then workflow hints, then security. No wasted words.

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

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

Covers pre-action (list_projects), post-action (create_task), idempotency, ownership, and security. Lacks error handling or explicit date validation, but schema handles that. Adequate for a create operation with 10 params.

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 covers 100% of parameters with descriptions, so description adds little beyond mentioning return value and idempotencyKey context. Adequate but not exceptional.

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

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

Clearly states 'Create a new project' with specific scope ('in the current organization') and side effects ('caller becomes the project owner'). Distinguishes from siblings like update_project by focusing on creation and referencing create_task for populating 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?

Provides explicit guidance to use list_projects first to avoid duplicates and notes that the returned ID can be passed to create_task. Does not explicitly list when not to use, but the context is clear enough.

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 indicate it's not read-only, but the description adds a security note about free-text fields being wrapped in <onplana_user_content> tags. However, it does not disclose other behavioral traits such as required permissions, side effects, or whether the proposal is persisted immediately.

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

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

The description is concise with two sentences plus a separate security note. It front-loads the main purpose and uses clear language, though the security note could be integrated more gracefully.

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 13 parameters, low schema coverage, and no output schema, the description omits many details like return values, prerequisites, and side effects. The security note adds some context, but overall completeness is insufficient for a creation tool.

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

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

Schema description coverage is only 46%, and the description does not elaborate on any parameters except indirectly through the security note. It adds no meaning beyond the schema, leaving many parameters without explanation.

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

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

The description clearly states the action ('Create'), the resource ('a DRAFT governance proposal'), and the lifecycle ('for review through the pipeline (DRAFT to APPROVED/REJECTED)'). This distinguishes it from sibling tools like 'advance_proposal_stage' or 'update_proposal'.

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 mentions 'Feature: governance (ENTERPRISE+)' and implies use for governance proposals, but lacks explicit guidance on when to use this versus alternatives like 'create_change_request'. No when-not-to-use or comparative context is provided.

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

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

Annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false) are minimal. The description adds substantial behavioral context: atomicity, error handling ('Out-of-scope or missing tasks are skipped with reasons; the sprint is still created'), required permission ('sprint.manage'), and a security note about user content tags. This far exceeds the annotation coverage.

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

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

The description is two paragraphs plus a concise security note, all front-loaded. Every sentence adds value: purpose, parameter summary, error behavior, permission, security. No fluff 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?

The tool has 7 required parameters and no output schema. The description covers creation behavior, error handling, permissions, and security. However, it does not describe the return value (e.g., the created sprint object) or mention the idempotencyKey parameter (present in schema). This is a minor gap given the lack of output schema.

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

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

Schema coverage is 86% (6/7 params have descriptions). The description adds constraints like 'up to 50' for taskIds, 'ISO' for dates, and clarifies that taskIds must be 'existing tasks on the same project'. For projectId (no schema description), it provides context. This adds meaningful value beyond 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?

The description clearly states the tool's purpose: 'Create a sprint on a project AND move existing tasks into it in one atomic call.' It specifies the verb (create), resource (sprint), and the combined action (move tasks). This distinguishes it from siblings like create_epic, move_task_to_sprint, or update_sprint.

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 says 'atomic call' and lists parameters, but does not explicitly state when to use this tool vs alternatives such as move_task_to_sprint (for moving to existing sprint) or update_sprint. It mentions out-of-scope tasks are skipped, but no guidance on prerequisites or when not to use.

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

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

Discloses write operation, permission requirement, and a security note about content wrapping. Consistent with annotations (readOnlyHint=false).

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

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

Two short, focused sentences plus a necessary security note. Front-loaded with core purpose. Every sentence contributes.

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 purpose, constraints, and permissions. Lacks return value description, but no output schema is provided. Adequate for a simple creation tool.

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

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

Schema coverage is 100%. Description adds format detail for color ('6-digit hex #RRGGBB') and repeats name length, providing slight value beyond 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?

Clear verb 'create' and resource 'tag/label' with scope 'org-scoped'. Distinct from sibling 'assign_tag' and 'unassign_tag'.

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 mentions required permission 'org.tag.manage' and parameter constraints. Lacks explicit when-not-to-use or alternative tools.

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

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

Annotations are minimal (no destructive/idempotent hints). Description adds idempotency key explanation and security note about user content tags, providing valuable behavioral context beyond 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-loaded with purpose, then guidelines, then edge cases and security. Every sentence earns its place without redundancy.

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

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

Covers core behavior, alternatives, optional params, and security. Missing detail on return value or error states, but acceptable given no output schema.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning with details like assigneeName as alternative, idempotency key behavior, and which params are required.

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

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

The description clearly states 'Create a task in an existing project' with specific verb and resource. It distinguishes from siblings by naming add_subtasks and instantiate_plan as alternatives for bulk operations.

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 when-to-use guidance: prefers add_subtasks for multiple children under same parent, prefers instantiate_plan for full project+task+risks creation, and suggests using list_projects to resolve project name to ID.

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 are present (readOnlyHint=false, destructiveHint=false), and the description adds value by noting that it creates a DRAFT entry and includes a security note about user content wrapping in <onplana_user_content> tags. This provides behavioral context 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?

The description is two clear sentences plus a security note. It is front-loaded with the main purpose. The security note is important but adds length. Overall, it is efficient and structured well.

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

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

The description covers creation of a draft entry with key constraints and feature requirement. However, it does not describe the return value (e.g., the created entry object), and there is no output schema. For a create tool with 6 parameters, the description is moderately complete but could include more about the result.

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

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

Schema description coverage is 50% (3/6 parameters have descriptions). The description reinforces constraints for 'hours' and 'date' but does not add meaning for 'taskId', 'projectId', or 'notes'. The idempotencyKey parameter is described in schema but not in description. The description partially compensates for the low coverage.

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

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

The description clearly states 'Log hours worked on a task (creates a DRAFT timesheet entry).' This specifies the action (log hours, create draft) and the resource (timesheet entry). It effectively distinguishes from sibling tools like approve_timesheet_entry, update_timesheet_entry, and list_timesheet_entries.

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 provides explicit constraints: 'Hours must be 0.25-24. Date must be today or in the past and within project dates. Feature: timeTracking (PRO+).' This helps an agent understand when to use this tool. However, it does not directly compare with alternatives like update_timesheet_entry, so it lacks clear when-not-to-use 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 indicate readOnlyHint=false and destructiveHint=false, which align with the description stating 'Create.' The description adds value by disclosing the plan gate (availability), the one-of constraint, and a security note about user content tags in results—beyond what 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?

The description is concise, with three sentences plus a security note. It front-loads the purpose, then addresses constraints, parameters, and plan gate. No unnecessary 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?

Covers core purpose, key constraints, plan gate, and security note. Lacks explanation of the 'description' parameter and does not specify return value (though no output schema exists). Missing details on nested objects (elements, appState) beyond naming, but this is partially addressed by 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 50% (only name, appState, elements have descriptions). The description compensates by explaining the mutual exclusivity of projectId/proposalId, that elements defaults to empty array, and that appState is optional. However, it does not describe the 'description' parameter or clarify types for projectId/proposalId.

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

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

The description clearly states the tool's purpose: 'Create a whiteboard.' It specifies the constraint of exactly one of projectId or proposalId, and distinguishes from siblings like update_whiteboard (update vs create) and list_whiteboards (list vs create).

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

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

The description provides usage guidance by noting the mutual exclusivity of projectId and proposalId, and the plan gate requirement (PRO+). However, it does not explicitly compare with other tools like update_whiteboard or list_whiteboards to guide when to use each.

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

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

Discloses write operation and access requirement. Includes a security note about user content being wrapped in tags. No contradiction with annotations (readOnlyHint=false). Adds valuable behavioral context beyond annotations.

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

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

Two paragraphs: first covers purpose and constraints, second is a necessary security note. Concise and front-loaded, though the security note is lengthy but important.

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?

Describes inputs and constraints, but omits return value (common for create tools). No output schema, so behavior after creation (e.g., returns created page ID) is not specified. This gap reduces completeness.

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

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

Schema covers 100% of parameters with descriptions. The tool description reinforces mutual exclusivity of projectId/proposalId, adds char limits for title and icon, and clarifies emoji constraint. Enhances understanding beyond 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?

Clearly states 'Create a wiki page' with verb and resource. Specifies scope (project or proposal) and distinguishes from sibling tools like update_wiki_page, get_wiki_page, list_wiki_pages. Also notes PRO+ feature.

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

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

Provides clear constraints: must provide either projectId or proposalId (not both), caller must have write access, title length limit. Does not explicitly state when not to use or alternatives, but context is sufficient.

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

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

The description adds value beyond annotations by explaining error behavior for unknown column ids, default order behavior, and the idempotency mechanism via idempotencyKey. Annotations already indicate it is a write operation (readOnlyHint=false) and not destructive. The description covers additional behavioral traits but omits return format and potential other errors.

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

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

The description is concise with two sentences of core detail plus a security note. It is front-loaded with the main action. The security note, while important, could be integrated more seamlessly but adds necessary context.

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 leaves out return information (e.g., what the tool returns after appending). It covers error behavior for unknown columns but not other errors or prerequisites. The security note adds completeness for user-input handling.

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%, and the description compensates by explaining the 'cells' parameter (map of columnId to value with types) and the 'order' parameter's default. However, it does not add meaning for 'tableId' or 'idempotencyKey' beyond what the schema provides.

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

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

The description clearly states the action ('Append a row') and resource ('workspace table'). It distinguishes from sibling tools like 'update_workspace_row' and 'list_workspace_rows' by specifying 'append' versus update or 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?

The description does not specify when to use this tool over alternatives, nor does it include when-not-to-use or exclusion criteria. It lacks explicit usage context beyond the basic operation.

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

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

The description adds behavioral details beyond annotations: atomic transaction for table+columns, idempotency key for safe retries, column order determines render order, and a security note about user content tags. It doesn't cover error handling or rate limits.

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

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

The description is concise (3 sentences plus security note) and front-loaded with the primary purpose. Every sentence provides essential information without redundancy.

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

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

Given the complexity (6 top-level parameters, nested objects, no output schema), the description covers key aspects: creation constraints, column types, idempotency, and security. Missing return format or error cases, but sufficient for typical use.

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 description significantly supplements the schema (33% coverage). It explains the mutually exclusive requirement for projectId/proposalId, lists all colType options, describes options and required fields for columns, and elaborates on the idempotencyKey. This adds critical meaning beyond the bare schema.

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

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

The description clearly states the tool's purpose: 'Create a workspace table.' It distinguishes from siblings like create_workspace_row by specifying that it creates the table itself, not rows. Constraints like 'exactly one of projectId or proposalId' add specificity.

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 provides clear constraints (exactly one of projectId or proposalId) and mentions that columns can be created atomically. However, it lacks explicit guidance on when not to use this tool versus alternatives (e.g., when to use create_workspace_row instead).

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. The description adds beyond: the calculation is deterministic (no LLM), prose falls back to template when AI unavailable, and includes a security note about user content tags. This provides a complete behavioral picture.

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?

Description is concise and well-structured. Each sentence adds value: what it does, output details, deterministic nature, fallback behavior, usage context, security note. No wasted words.

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

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

Given the tool's simplicity (1 param, no output schema, comprehensive annotations), the description fully covers purpose, behavior, and usage context. It is complete for an agent to correctly select and use the tool.

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

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

Only one parameter (projectId) with 100% schema description coverage. The description does not add any additional meaning beyond the schema's description. Following the guidelines, baseline is 3 when schema coverage is high.

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

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

The description clearly states that the tool computes the critical path and returns a prose summary. It specifies the output elements (ordered task IDs, bottleneck, end date, duration, explanation). This distinguishes it from siblings like 'leveling_narrative' which deals with resource leveling.

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 usage guidance: 'Use before planning sessions or when the user asks...'. It also notes 'No plan gate' indicating unrestricted availability. This clearly tells the agent when to invoke this tool versus others.

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

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

The annotations (readOnlyHint, destructiveHint, idempotentHint all false) are not contradicted. The description adds valuable behavioral details: duplicate decisions return CONFLICT, the workflow engine picks up the decision asynchronously, and a security note about user content wrapping. It goes beyond the annotations to clarify behavior.

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

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

The description is concise, with the core purpose in the first sentence, followed by key usage notes. The security note is necessary and appropriately placed. It is slightly longer than minimal but remains well-structured and front-loaded.

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

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

Given the tool has no output schema, the description provides necessary context: prerequisites (assigned approver), behavior on duplicates (CONFLICT), asynchronous processing (next tick), and plan gate. Parameter coverage is adequate. It is complete for the complexity level of this tool.

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

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

With 0% schema description coverage, the description carries the burden. It explains the 'decision' parameter's allowed values (APPROVED, REJECTED) and mentions the 'note' as optional. However, it does not explicitly describe 'approvalId' beyond context, but the purpose is clear from the tool's name. Overall, it adds meaningful meaning to the majority of parameters.

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

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

The description explicitly states the action ('Decide') and the resource ('PENDING workflow approval'), with the two possible outcomes ('APPROVED or REJECTED'). It clearly distinguishes this tool from siblings by focusing on the specific act of approving or rejecting a pending approval, which is unique among the listed sibling tools.

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

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

The description provides clear usage constraints: the caller must be the assigned approver, duplicate decisions result in CONFLICT, and the tool is gated by plan level (PRO+). While it does not explicitly mention alternatives or when not to use it, the context is sufficient for an agent to determine applicability.

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

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

Beyond annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description adds critical context: results include planSatisfied and permissionSatisfied fields for predicting authorization failures, a security note about user content tags, and source-of-truth guidance. No contradictions.

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

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

The description is well-structured, starting with the core purpose, then return fields, filters, usage tip, source, and security note. It front-loads key information, though slightly verbose. Each sentence earns its place.

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

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

For a tool with no output schema, the description thoroughly explains all returned fields, filtering options, usage recommendation, data source, and security considerations. It leaves no gaps for effective invocation and interpretation.

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 describes the 3 optional parameters (kind, mcpOnly, availableOnly). The description only restates them without adding new meaning, so baseline 3 is appropriate.

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

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

The description clearly states the tool returns the live MCP tool surface for the calling org, listing each row's fields like name, description, kind, featureKey, etc. This distinguishes it from sibling tools that return data, not tool definitions.

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

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

The description advises calling this after whoami to ground the session's tool model, and explains its utility for predicting 402/403 errors before calling other tools. It does not explicitly state when not to use it or alternatives, but the unique purpose is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds meaningful context: the source is a hand-curated catalog mirroring prisma schema plus validate() rules, and includes a security note about wrapping user content in tags. This goes beyond what annotations alone 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?

The description is moderately long but well-structured: first sentence states purpose, then enumerates modes, followed by usage guidance, and a security note. Each sentence earns its place. Minor reduction in verbosity could improve conciseness, but overall it is efficient and logically ordered.

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 details what each call returns (list of entity names vs. full descriptor with fields, relations, state machines, etc.). It also covers the special projectId merging behavior. It is complete enough for an agent to understand the tool's output without needing an output schema.

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

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

All three parameters have full schema descriptions (100% coverage). The description goes significantly further by explaining the behavior of each call mode—e.g., omitting entity lists all names, entity with projectId merges custom fields, includeAll returns bulk payload. This adds substantial value over 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?

The description starts with a clear verb 'Return the canonical Onplanta entity schema' and details three distinct call modes (no args, entity=<name>, includeAll=true). It distinguishes itself from sibling data retrieval tools like get_task by explicitly referencing schema introspection vs. sample row introspection.

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 explicit guidance on when to prefer this tool: 'PREFER calling this when planning against an empty org... or when validating writes that have cross-field rules.' It also explains the projectId parameter's role for custom fields. While it doesn't explicitly say when not to use it, the preference statement is strong and context-rich.

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

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

Annotations already indicate idempotent and non-destructive. The description adds value by explicitly stating idempotency, required permission, user prerequisite, and a security note about handling user-generated content. This goes beyond what 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?

The description is concise with three main sentences plus a security note. It front-loads the core action and efficiently adds prerequisites and idempotency. The security note, though not about the tool itself, is important context.

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

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

Given the tool is a simple mutation with no output schema, the description covers necessary context: prerequisites, permissions, idempotency, and security. It provides enough information for an agent to use the tool correctly, though missing return value details.

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

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

Schema description coverage is 50% (only userId has a description). The description does not elaborate on the parameters beyond the general action wording. It does not clarify that gate is an enum or explain the values, so the description fails to compensate for the schema's lack of detail.

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

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

The description clearly states the tool's purpose: designating a user as a gate reviewer for a specific governance gate. It includes the verb 'designate' and resource 'gate reviewer', and references the governance feature. While it doesn't explicitly distinguish from sibling tools like list_gate_reviewers, the action type is 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?

The description provides some usage guidelines: required permission (org.governance.manage), prerequisite (active org member), and feature tier (ENTERPRISE+). However, it lacks explicit guidance on when to use this tool versus alternatives (e.g., removing reviewers, submitting reviews) and when not to use it.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds heuristic thresholds (>=80% tasks, at least one rate card) and a security note about user content tags, which is useful beyond annotations.

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

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

Two short paragraphs with clear purpose, return values, and a security note. No fluff.

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?

Simple tool with one parameter and no output schema. Description fully explains behavior, return values, and usage context, including security considerations.

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

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

Only one parameter 'projectId' with 0% schema coverage. Description does not explicitly describe the parameter, but its name and context ('for a project') make it obvious. Minimal additional value beyond 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?

Clearly states the tool probes the cost-attribution path for EVM and lists specific return values ('imported', 'rate-cards', 'none') with conditions. Differentiates from sibling 'calculate_evm' by being a pre-flight check.

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

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

Explicitly says to use before calling 'calculate_evm' to warn about low fidelity. Doesn't explicitly state when not to use, but the context is clear.

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

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

The description confirms the destructive action (delete) and adds a security note about user content tags, which goes beyond the annotations (destructiveHint=true, idempotentHint=true). No contradiction.

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

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

Two sentences plus a security note; every sentence adds value. The primary action is front-loaded and clear.

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 parameters and no output schema, the description adequately explains the tool's purpose and pairing. It could mention the effect is immediate and irreversible, but the destructive hint covers that.

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

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

The input schema has no parameters (100% coverage), and the description correctly adds no additional parameter information since none are needed.

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

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

The description uses a specific verb ('Delete') and resource ('every already-read notification for the calling user'), clearly distinguishing it from siblings like mark_all_notifications_read (which marks as read) and dismiss_notification (single notification).

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 states when to use (to delete read notifications) and suggests pairing with mark_all_notifications_read. It does not explicitly list exclusions, but the context and sibling names imply when not to use.

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

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

Annotations already indicate destructiveHint and idempotentHint. The description adds that deletion is permanent and removes from inbox. It also includes a security note about user content tags. No contradictions with annotations.

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

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

Two concise sentences plus a necessary security note. No wasted words; the purpose and key constraint are front-loaded.

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

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

For a simple destructive action with one parameter and no output schema, the description covers the core purpose, ownership requirement, and security handling. It could mention return value, but not essential.

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

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

Schema coverage is 100%, so the parameter is already fully documented. The description does not add extra semantic context beyond the schema's description of notificationId.

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

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

The description clearly states it permanently deletes one notification and removes it from the inbox. It uses a specific verb ('delete') and resource ('notification'), and distinguishes from siblings like dismiss_all_read_notifications or mark_notification_read.

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