Sync Day

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

The annotations are all false/default and provide no behavioral safety signals, so the description carries the full burden. It explicitly discloses the day-range semantics (inclusive endDate or days), the candidate-time generation rule (start + durationMinutes <= hourTo), return fields, and the confidentiality split between public URL and adminKey.

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 uses four dense, purposeful sentences and a concrete example. The purpose is front-loaded, the time-window logic is compressed into one clear sentence, and the example maps natural-language intent to actual parameter values without waste.

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

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

With no output schema, the description correctly enumerates the returned slug, public url, adminUrl, and adminKey, and explains their privacy roles. It covers the core algorithm and provides an example, but it does not mention that endDate wins over days when both are supplied; that precedence is only in the schema. Overall it is nearly complete for a 9-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 description coverage is 100%, so the baseline is 3. The description adds real cross-parameter meaning by explaining how startDate, endDate/days, hourFrom, hourTo, startStepMinutes, and durationMinutes combine to generate candidate slots. It doesn't individually cover optional parameters like question, but the schema already documents those.

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

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

The description opens with a specific verb and resource: 'Create a sync.day availability poll and get its share link.' It clearly identifies the tool as a creation action and distinguishes it from sibling tools by noting that the returned adminKey is needed for update_event and remove_participant.

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

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

The description gives clear context for using the tool: create a poll, define the candidate day/time window, and share the public URL while keeping adminKey private. It references update_event and remove_participant as follow-up operations, but does not explicitly state when not to use create_event or when an alternative sibling would be preferred.

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 the locking side effect, the UI change ('page shows 已定'), the reopening behavior via null, and the admin-only scope. This goes well beyond the annotations, which only indicate a non-read, idempotent, non-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?

Three short sentences cover scope, purpose, side effects, the reopen case, and required credentials. The most important information is front-loaded and every sentence earns its place.

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

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

For a small mutation tool with three fully documented parameters and no output schema, the description covers who may call it, what it does, what side effects occur, and how the null case behaves. No critical calling context is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description mostly restates what the schema already says about start and adminKey; the main added nuance is the behavioral pairing of start=null with reopening, but that is also present in the schema's parameter 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 states a specific verb and object: 'settle on a start time', and clarifies the effect by 'locks availability picking and voting; the page shows 已定'. This clearly distinguishes it from voting tools like vote_time and generic mutation tools like update_event.

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

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

It explicitly restricts usage to organisers ('Organiser only'), names the required credential ('adminKey from create_event'), and documents the reopen case with 'Pass start=null to reopen'. It does not name alternatives explicitly, 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?

Beyond the readOnlyHint annotation, the description adds valuable behavioral detail: no authentication key is needed, participants can have repeated names, returned start options are ranked by head-count, and only voteOptions usable by everyone with picks are returned. This meaningfully informs the agent about edge cases and response semantics that the schema and annotations do not 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 front-loaded with the core action and then delivers a dense but purposeful list of returned fields. It is somewhat long and run-on, but every clause adds useful information and nothing is wasted.

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

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

With no output schema present, the description carries the full responsibility of explaining return values, and it does so thoroughly: it names every major result group and notes the no-key requirement. For a single-parameter read tool, the agent has enough information to call it correctly and interpret the result.

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

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

Schema description coverage is 100% for the single slug parameter, and the schema already explains its format and example. The description does not add parameter-level details, but it does not need to; the baseline of 3 applies.

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

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

The description opens with a specific verb and resource, 'Read an event', and then enumerates exactly what data is returned: settings, startOptions, participants, ranked start times, voteOptions, votes, and decidedStart. This clearly distinguishes it from the mutating sibling tools like create_event, update_event, and vote_time.

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 'Read an event' framing plus the readOnlyHint annotation makes the retrieval purpose clear, and 'No key needed' tells the agent a key is not required before calling. It does not explicitly name alternatives or state when not to use it, but the context is unmistakable alongside the mutating 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?

The annotations already flag readOnlyHint=true, and the description reinforces this by stating 'Does NOT create anything'. It adds useful behavioral context beyond annotations: the use of 'sync.day's AI parser' and that the result should be reviewed before creating. No contradiction with the read-only annotation.

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 with no filler. Each sentence serves a purpose: defining the action, clarifying the non-destructive workflow, and giving a concrete example. Front-loaded with the core purpose and immediately followed by the critical 'does NOT create anything' caveat.

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, the description adequately communicates the output as 'create_event input' and instructs the agent to review before creating. Combined with the readOnly annotation and the example, it fully equips the agent to invoke the tool and handle the result safely. There is no missing critical information for such a simple tool.

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

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

The schema already covers both parameters with descriptions (text max 300 chars, today format and default). The description adds an example and notes 'Chinese works best', but does not add significant parameter-level semantics beyond what the schema provides. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description names a specific verb ('Turn'), a clear input ('natural-language sentence'), and a concrete output ('create_event input'). It explicitly says it 'Does NOT create anything', which distinguishes it from the sibling create_event tool. The example further clarifies the expected input format.

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

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

It clearly states when to use the tool: when you have natural language to convert to event input. It also provides a workflow ('review the result, then call create_event') and a language hint ('Chinese works best'). It does not explicitly mention when not to use it or compare it to alternatives like decide_time, but the context is clear enough for an agent to select 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 the annotations (destructive, idempotent), the description discloses specific behavioral details: it removes the participant's vote, and when names repeat it targets the oldest row. It also surfaces the auth requirement (adminKey), which is not carried by annotations alone.

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

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

Two tight sentences: the first front-loads the core action and constraints, the second clarifies the required credential source. There is no redundant phrasing or filler; every sentence earns its place.

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

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

For a simple destructive operation with three well-documented parameters and annotations covering idempotence and destructiveness, the description supplies the essential context: organizer-only access, the adminKey dependency, the exact removal target, and duplicate handling. Nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying the tie-breaking rule for the name parameter ('oldest row') and by specifying that adminKey comes from create_event, enriching the parameter semantics beyond the schema text.

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

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

The description uses a specific verb ('remove'), names the resource ('one participant by name'), and clarifies the scope ('together with their vote'). It also states the organizer-only restriction, which differentiates this from other event-editing siblings like update_event or vote_time.

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: it is organizer-only and requires the adminKey from create_event. It does not explicitly name alternatives or exclusions, but the prerequisites make the usage context unambiguous and the tool has no direct sibling with a similar function.

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

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

The description adds key behavioral context beyond the annotations: same identity overwrites and can rename the row, same name with different identity is a second participant, invalid start keys are rejected, and the updated ranking is returned. These details make the idempotentHint meaningful and prevent misuse.

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

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

Three sentences front-load the core action and then layer only high-value caveats. No sentence is wasted; every clause (overwrite, name collision, rejection, return value) contributes to correct invocation.

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

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

For a 4-required-parameter write action with idempotent semantics, the description plus fully covered schema and annotations is complete. It states the source of valid keys, the overwrite behavior, validation, and return value, so an agent has enough context to call it correctly without an output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by tying starts to get_event.startOptions and detailing identity-based overwrite/rename semantics. It does not fully describe every parameter, but the schema already covers the rest.

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

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

The description opens with a specific verb-resource pair, 'Save (or replace) one person's availability', and immediately defines the scope by identity and start options. It distinguishes the tool from siblings like update_event or decide_time by its focus on a single person's availability rather than event-wide settings or scheduling decisions.

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

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

It gives clear context: the availability must use start keys from get_event.startOptions and invalid keys are rejected, so an agent knows when input is valid. It does not explicitly name alternatives or state when not to use the tool, so it falls just short of full routing guidance.

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

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

The description discloses substantial behavior beyond the annotations: partial-update semantics ('omitted fields keep their current value'), a field precedence rule ('endDate wins over days'), and the side effect on existing data ('picks are kept; those no longer valid starts are just hidden'). For a mutation tool this is exactly the context an agent needs, and it does not contradict idempotentHint=true since repeated identical updates converge to the same state.

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

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

Two sentences with zero waste. The most decision-relevant constraint ('Organiser only') is front-loaded, and every remaining clause conveys a distinct behavioral rule: field parity with create_event, patch semantics, precedence, and pick preservation. Nothing is repeated from the schema.

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

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

The description covers the auth prerequisite, patch semantics, precedence rule, and the non-destructive handling of existing picks — the key things an agent needs for a mutation with no output schema. The main gap is that 'same fields and rules as create_event' makes full correctness dependent on the sibling tool's documentation, and error/response behavior is not mentioned, which is a minor omission for a settings-update 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%, so the baseline is 3. The description adds genuine value above the schema: it clarifies that all fields except slug/adminKey are optional patch-style updates, and it resolves the endDate-vs-days ambiguity with an explicit precedence rule that the schema states less authoritatively. The 'same fields and rules as create_event' line also signals cross-tool consistency for parameter interpretation.

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

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

The description names a specific action ('change') and a specific resource ('any event settings'), and immediately qualifies it with 'Organiser only'. This cleanly separates it from create_event (creation), get_event (read-only), and vote_time/submit_availability (participant flows). The verb+resource+scope combination leaves no ambiguity about what the tool does.

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?

'Organiser only' is a clear usage gate that excludes participant-facing tools like submit_availability and vote_time, and 'same fields and rules as create_event' anchors the tool to the event-management flow. However, it doesn't explicitly name alternatives or spell out 'use create_event to create a new event', so some routing context is implied rather than stated.

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

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

The description goes well beyond the annotations by disclosing that earlier approvals are replaced, that an empty list clears approvals, that a valid identity with a saved start is required, and that invalid keys produce an error listing the current options. It also clarifies that the tool is rejected after the organiser decides. These behavioral details add substantial value and do not contradict the annotations; the idempotentHint aligns with the replace/set semantics.

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 dense but every sentence earns its place: it front-loads the core behavior, then adds constraints, error behavior, a rejection condition, and a concrete example. Nothing is redundant 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 complexity and lack of an output schema, the description covers all invocation-critical aspects: required identity linkage, accepted key source, clearing behavior, rejection after decision, and the shorthand. An agent has enough context to call the tool correctly without additional lookups.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining that `identity` must be the same one used in submit_availability, that accepted starts come from get_event.voteOptions, and that `start` is shorthand for a single-item `starts`. The included example also clarifies how slug, identity, and starts fit together.

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

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

The description states a specific verb and resource: 'set every start one person accepts', and frames it as 'approval voting', distinguishing it from the initial availability submission tool. It also references get_event.voteOptions and the organiser's decision, which separates it from decide_time. This is specific enough for an agent to select it correctly among the siblings.

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

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

The description gives clear usage context: the voter must have already saved at least one start via submit_availability, only keys from get_event.voteOptions are valid, and the tool is rejected once the organiser has decided. It also explains the effect of an empty list, which is essential for using the tool correctly. This effectively communicates when to use the tool and when not to.

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