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

With no annotations, the description carries the full burden of disclosing side effects. It explicitly states that it immediately creates a durable store record AND a Linear ticket, and that it deduplicates against existing commitments. This is key behavioral information, though it could add details on idempotency or failure handling.

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

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

The description is three sentences, front-loaded with the core purpose, then side effects, then dedup. No wasted words; 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?

Despite having no output schema and no annotations, the description explains what the tool returns, its side effects, and its dedup behavior. It does not cover potential edge cases or the exact output format, but for a tool with 4 parameters and clear side effects, 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?

Schema description coverage is 100%, so the baseline is 3. The description does not add significant parameter-specific details beyond what the schema already provides, but it does frame the overall purpose (transcript parsing) which indirectly applies to parameters like transcript_text and meeting_date.

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 parses a meeting transcript and returns structured commitment objects, with a specific verb and resource. It also distinguishes itself from siblings like upsert_commitment and query_commitments by emphasizing the extraction and automatic ticket creation behavior.

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

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

The description implies usage for meeting transcripts and mentions catching commitments that would otherwise be missed, providing clear context. It does not explicitly name alternative tools or exclusions, but the context is sufficient for an agent to infer when 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?

With no annotations provided, the description carries the full burden. It discloses the output content (transcript with participants/date), the presence of a transcript_text field, and the intended behavior ('designed to exercise all three confidence levels'). Could mention that it's a static sample or has no side effects, but adequate for a 0-param getter.

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

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

A single, well-structured sentence front-loads the core purpose and immediately follows with usage guidance. Every clause provides value, no redundancy or filler.

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

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

For a simple, parameterless tool with no output schema, the description fully covers the return value's key fields and the intended use case. It tells the agent exactly what to expect and how to chain it with extract_commitments, making the tool self-sufficient.

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

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

The input schema has zero parameters, so the baseline is 4. The description adds meaning by explaining the return value's structure, and no parameter documentation is 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?

Clearly states the tool 'returns a ready-to-use sample meeting transcript' with specific content details ('participants and meeting date'). Distinct from sibling tools focused on commitments/status, and specific about its role in the demo flow.

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 directs usage: 'paste its transcript_text into extract_commitments to run the demo flow.' Names the sibling tool and the exact integration step, making when and how to use it unambiguous.

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

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

With no annotations provided, the description carries the full burden. It adds a meaningful security-related behavior: 'Keys stay server-side in the Linear service; this tool never exposes them to the model.' However, it does not disclose other behavioral aspects such as idempotency, potential duplicate tickets, or side effects, so it is adequate but not comprehensive.

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

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

The description is two sentences: the first states the action and purpose, the second adds a crucial security detail. Both sentences earn their place with no redundancy or filler.

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

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

For a simple create tool with no output schema, the description is largely complete: it explains why the tool exists (preventing commitment loss) and the security model. However, it omits information about the return value or any failure modes, which would be useful but not essential given the tool's simplicity.

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 does not discuss any of the five parameters. Schema description coverage is only 40%, leaving labels, title, and assignee_email without meaningful descriptions in either the schema or the tool description. The description fails to compensate for this gap, providing no 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 the verb 'Creates a Linear ticket' and the specific resource (Linear ticket), with the context of 'newly extracted commitment' that distinguishes it from sibling tools like linear_update_status. It also conveys the purpose 'so it's never lost', making the tool's intended role immediately 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 implies when to use it: for newly extracted commitments that might otherwise be missed ('even commitments nobody manually ticketed'). It provides clear context but does not explicitly state when not to use it or name alternative tools, so it falls short of a 5.

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

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

No annotations are present, so the description carries the full burden. It discloses the primary side effects (adding a watcher, posting a comment with specified content) but omits other potential behavioral details like status changes, notification side effects, permission requirements, or reversibility.

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

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

The description is a single, tightly written sentence that is front-loaded with the primary verb and action. It avoids redundancy and gets to the point immediately.

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

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

With no output schema and no annotations, the description is too brief to cover important context such as return values, error conditions, side effects beyond the comment, or why this tool should be preferred over sibling tools. It reads like a minimal action summary rather than a complete tool guide.

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

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

Schema description coverage is only 33%, with only context_comment described in the schema. The description adds meaning for context_comment (mentioning what was promised, tried, and why surfaced) and loosely clarifies manager_email, but ticket_id and email format remain under-specified.

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 a specific action: 'Adds a manager as a watcher' on a ticket and adds a context-rich comment. This distinguishes it from sibling tools like linear_update_status or linear_create_ticket.

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

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

No guidance is given for when to use this tool versus alternatives such as send_nudge or linear_update_status. The description explains the action but not the appropriate escalation context or 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?

No annotations are provided, so the description carries the full burden. It identifies the tool as a read operation, implying non-mutating behavior, but adds no other context like error handling, auth, or output format.

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

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

One concise sentence, front-loaded with the action, 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?

For a simple read tool with one parameter and no output schema, the description covers the purpose, the object, and a use case. It lacks some edge-case details but is largely 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?

The schema has one parameter with zero description coverage. The description refers to a 'Linear ticket' but does not explain ticket_id format or add any detail beyond the schema. It provides minimal compensation 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 the tool reads the current status of a Linear ticket, using a specific verb and resource. It distinguishes from sibling update/escalate tools by implying a read-only operation, though it does not explicitly name alternatives.

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

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

It provides a concrete use case ('used by the scheduler to verify work marked Done in Linear') and contrasts with Slack/email verification. However, it does not explicitly state when not to use this tool or name alternative Linear 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?

With no annotations provided, the description carries the full burden of disclosing behavior. It only says 'Updates the status' and vaguely references the scheduler, but does not explain side effects, validation rules, permissions, or what happens after the update. This is a significant gap for a mutation tool.

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

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

The description is concise, using two short sentences with no redundant content. It front-loads the core purpose. The second sentence adds useful context, though it could be phrased more clearly.

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 update tool with only two parameters, the description gives enough to understand the basic operation. However, the lack of output schema and annotations, combined with vague scheduler behavior, leaves gaps around return values and side effects. The description is adequate but not thorough.

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 has two parameters with 0% description coverage, and the description does not mention them at all. While the status enum is self-explanatory, ticket_id's meaning and format are not clarified, leaving the description to compensate for the schema gap but failing to do so.

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 ('Updates the status of a Linear ticket') and adds context about the scheduler picking up manually Done tickets. It is specific about the resource and verb, though it does not explicitly distinguish it from sibling linear_escalate, which might also change status.

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

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

The second sentence implies a specific use case (letting the scheduler pick up a manually Done ticket), providing some contextual guidance. However, it does not explicitly state when to avoid this tool or name alternatives like linear_escalate, leaving the usage boundaries somewhat implicit.

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

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

With no annotations, the description carries the full burden. It discloses the key behavioral consequence ('moves an idea into the follow-up loop', 'scheduler starts actively chasing it'), but does not mention reversibility, side effects, or what happens if the commitment is already promoted. This is adequate but not rich.

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

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

Two concise sentences, front-loaded with the verb 'Promotes'. Every sentence adds value—the first defines the action and result, the second clarifies the human-override nature. 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 an enum, the description covers the main behavioral outcome and the purpose. It does not explain return values or edge cases, but the simplicity and the fact that it's a mutation tool make this mostly 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 only 50%; commitment_id has no schema description. The tool description does not mention any parameters by name or explain how they map to the action, leaving the meaning of commitment_id implicit. It adds little beyond what the schema already provides for confidence_level.

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: 'Promotes a logged aspirational commitment' with a specific resource ('aspirational commitment') and a clear outcome ('scheduler starts actively chasing it'). It distinguishes itself from siblings like query_commitments or extract_commitments by focusing on the promotion action.

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: 'This is the human override' indicates when to use the tool (human intervention) versus automatic processing. It does not explicitly name alternatives or exclusions, but the context is sufficient for basic 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?

With no annotations, the description carries the disclosure burden. It clearly indicates a read-only operation ('Returns') and warns that omitting filters returns every commitment, which is a significant behavioral caveat. However, it does not describe the return format, pagination, or permissions, leaving some behavioral aspects undisclosed.

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 sentences that lead with the verb and core behavior, followed by a useful edge-case note ('no filters returns every commitment'). There is no wasted wording or 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?

The tool is a simple filtered query with optional parameters; the schema covers parameter meanings, and the description explains the purpose and no-filter behavior. However, since there is no output schema, a brief mention of return shape or ordering would improve completeness, though the current description is largely sufficient.

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

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

The input schema already documents all three parameters with descriptions, achieving 100% schema description coverage. The tool description adds no additional parameter semantics beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description uses the specific verb 'Returns' with the resource 'commitments matching a filter', making the tool's function immediately clear. It also distinguishes this query tool from sibling mutation tools like upsert_commitment and send_nudge by focusing on retrieval and filtering.

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 it is used by the scheduler to find items due for poll or nudge checks, providing a concrete when-to-use context. It also notes that with no filters it returns every commitment, which is an implicit warning about broad results. It does not explicitly mention alternative tools, but the use case 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?

No annotations are provided, so the description carries the burden of indicating destructive behavior. The verb 'wipes' clearly conveys that data is erased, and 'resets the virtual clock' is explicit about the clock behavior. It could go further by stating irreversibility, but the language is sufficient for a destructive operation.

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

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

The description is two sentences, front-loading the action and then providing usage context. Every word earns its place; there is no redundancy or filler.

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

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

Given the tool's simplicity (no parameters, no output schema), the description is complete. It covers what the tool does, what stores are affected, and when to use it. It also differentiates from sibling 'simulate_days_passing' by specifying it resets to today.

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 and the schema coverage is 100% (trivially). The description adds no parameter information, but none is needed since the tool takes no inputs. The baseline of 4 is appropriate for a parameterless tool.

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

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

The description clearly states a specific verb ('wipes', 'resets') and identifies the exact resources affected (commitment store, ticket store, virtual clock), making it distinct from siblings like 'simulate_days_passing' (which advances the clock) and 'upsert_commitment' (which modifies individual records).

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 when to use the tool: 'Use this to restart the demo scenario cleanly.' It does not explicitly exclude other tools, but the context is clear enough that an agent would know this is for resetting demo state rather than for ongoing operations.

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

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

With no annotations, the description carries full burden. It only says 'searches' (implied read-only) and 'mocked' (test environment), but does not disclose return format, ordering, pagination, side effects, or any safety details. This is a significant gap for a tool operating on a store.

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

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

The description is a single sentence with no fluff, front-loaded with the action and then a helpful example that justifies the tool's existence.

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 is simple, but with no output schema, the description should at least hint at what is returned. It does not mention return values, result caps, or any limitations. Example usage helps, but completeness is only 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 67% (2 of 3 params described). The description adds domain context (external beneficiary, shipped work) that clarifies query terms, but does not fully explain how params interact or what to_domain_hint does beyond the schema example.

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 searches a mocked inbox/sent-items store for emails relevant to a commitment, with a concrete example. It distinguishes from sibling tools like search_slack_evidence by focusing on email evidence, though it does not explicitly name the alternative.

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 example (mail sent to an external beneficiary) provides clear context for when to use the tool. It does not explicitly exclude other tools or list alternatives, but the use case is well-illustrated.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It accurately notes that results are raw candidate messages and that semantic scoring is the verification agent's responsibility—not the tool's. This is honest about the tool's limitations and the need for downstream processing, though it omits details like rate limits or result 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 two sentences, front-loaded with the primary action and purpose, and includes only essential context about return behavior. No filler or redundancy.

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

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

For a straightforward search tool with four well-documented parameters and no output schema, the description provides sufficient context: it clarifies the purpose, the nature of results (raw candidates), and how results should be consumed. It could mention result limits or sorting, but that is minor given the tool's simplicity.

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 each parameter having a description. The tool description adds no additional parameter-level detail beyond the schema, so the baseline of 3 is appropriate. It does not explain parameter interactions or provide examples.

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

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

The description clearly states the tool's function: searching Slack for messages that could constitute evidence a commitment was fulfilled. It specifies the resource (Slack messages), the purpose (evidence of fulfilled commitments), and distinguishes it from the sibling search_email_evidence by scope and result handling.

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

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

The description implies usage context: use this tool when you need to find Slack messages as evidence of commitment fulfillment. It does not explicitly name alternatives or exclusions, but the sibling list includes search_email_evidence, and the Slack-specific scope makes the intended context 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?

With no annotations, the description carries full burden. It discloses that the reminder references 'original commitment language and deadline', implying the tool fetches commitment data. But it does not mention delivery guarantees, authentication needs, or potential side effects like notifications, leaving some ambiguity.

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 with no filler. First sentence establishes purpose; second provides tone calibration. Information is front-loaded, making it easy to scan.

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 5 parameters and no output schema or annotations, so the description needs to cover more ground. It adequately covers purpose and tone, but misses explicit alternatives, delivery behavior, and output/confirmation details. Given moderate complexity, it's minimally viable but not rich.

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

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

Schema coverage is only 40%, but the description compensates by clarifying the tone parameter's intended progression ('gentle first, specific second, urgent only on hard blockers'). It also explains that the reminder references original commitment language and deadline, giving meaning to commitment_id and message_body. However, it doesn't explicitly detail all parameters, so compensation is partial.

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

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

The description clearly states 'Sends a contextual reminder to the commitment owner via Slack or email', identifying the specific action, target, and channels. It also distinguishes itself from siblings like linear_update_status by focusing on nudging rather than status updates.

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 tone calibration guidance ('gentle first, specific second, urgent only on hard blockers') provides clear context for when to use each tone. However, it lacks explicit comparison to alternative tools or conditions, so it doesn't fully meet the 'when-not-to-use' 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?

With no annotations, the description carries the full burden. It discloses the core behavior (advancing the clock, triggering one scheduler poll) and explains the demo purpose, which implies potential cascading effects like nudges or escalations. It could add more detail about exact side effects or return values, but it provides a solid behavioral model.

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

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

The description is two sentences: the first states the action, the second provides context and rationale. Every sentence earns its place, with no filler or repetition. The 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?

For a one-parameter demo tool with no output schema, the description covers the mechanism (clock advance, scheduler poll), the purpose (demo lifecycle), and the contrast with production. It does not explicitly state what the agent sees after calling it, but the context of 'making the lifecycle observable' implies a sufficient outcome. Overall, it is complete 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 input schema covers 100% of the parameter with a clear description ('Number of days to fast-forward'), so the baseline is 3. The tool description reiterates 'N days' but adds no new semantic detail (e.g., allowed range, units, or consequences of large values) beyond what the schema already states.

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

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

The description clearly states the tool's action ('Advances the internal clock by N days and runs one scheduler poll') and identifies it as a demo control, distinguishing it from production scheduler behavior and sibling tools like reset_demo and send_nudge. This specificity makes its purpose 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 explicitly frames the tool as a demo control for making a week of chasing observable, and contrasts with production where the scheduler polls on a real interval. This tells the agent when to use it (live demos) and implicitly not to rely on it in production. It doesn't name alternative sibling tools, 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that the store is durable and the source of truth for lifecycle state, but it fails to explain key behaviors such as whether updates are partial or full replacements, how existing records are matched (e.g., by commitment_id), idempotency, or potential side effects like overwriting fields. This is a significant gap for a write operation.

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

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

The description is extremely concise—two short sentences—and immediately front-loads the core action and resource. No filler or redundancy. Every word contributes purpose or 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 complex nested schema, no annotations, and no output schema, the description is insufficiently complete. It communicates the basic upsert semantics but leaves out essential operational details: what fields are required to create a valid commitment, how updates are applied, how the tool identifies an existing record, and what the response contains. An agent would struggle to correctly invoke this tool for real tasks.

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 only one parameter 'commitment' with rich nested structure but zero property descriptions. The description adds no meaning beyond the schema, merely calling it a 'commitment record'. It does not explain any of the nested fields, required subfields, or the significance of fields like status, confidence_level, or nudge_log. With 0% schema description coverage, the description fails to compensate.

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

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

The description clearly states the tool's function with a specific verb 'Creates or updates' and a specific resource 'commitment record in the durable store'. It distinguishes itself from sibling tools like query_commitments (read) and extract_commitments (extraction), and the 'source of truth' phrase reinforces its authoritative write 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?

The description implies usage for creating or updating commitments, but it does not explicitly state when to use this tool versus alternatives like promote_commitment or send_nudge, nor does it mention when not to use it. The 'source of truth' statement provides some context but no direct exclusions or alternative recommendations.

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