sync-day

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

Annotations only convey generic flags (readOnly false, idempotent false, etc.), so the description carries the behavioral burden. It discloses the creation side effect, the date/time generation rules, the returned fields (slug, public url, adminUrl, adminKey), and the important security instruction to keep adminKey private. This goes well beyond the structured annotation data and has 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 dense but efficient: purpose first, then the generation rule, then return values, then an illustrative example. The 'days' aside is slightly ambiguous and adds some confusion, but every major sentence earns its place and the structure 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?

Since there is no output schema, describing returns (slug, public url, adminUrl, adminKey) is essential and is done clearly. It also covers the core input semantics and example scale. It would be more complete with an explicit clarification of the optional `days` parameter and the endDate-vs-days precedence, but overall it equips an agent to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a conceptual algorithm and a concrete example mapping natural language to parameters (title, startDate, endDate, hourFrom, hourTo, durationMinutes, startStepMinutes). The weakness is that the 'or give days instead' option is left vague and does not clarify the confusing `days` property in the schema, so it does not fully resolve every parameter.

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

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

States a specific verb+resource: creates a sync.day availability poll and returns the share link. The description also explains how candidate days/times are generated, which makes the purpose concrete. It does not explicitly distinguish itself from siblings like decide_time or update_event, so it stops short of a 5.

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

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

No explicit guidance on when to use create_event versus alternatives. The only related-tool hint is that adminKey is needed later for update_event / remove_participant, which is forward-looking usage advice, not tool-selection guidance. An agent must infer when to use this tool from the name/title.

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 key side-effect: locking availability picking and voting, and that the page shows 已定. It also mentions reopening with start=null and the adminKey requirement, adding meaningful behavioral context beyond the idempotent/read-only 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?

Three short sentences with no filler. The most important constraint ('Organiser only') is front-loaded, followed by the primary action, side-effect, and the reopening behavior.

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 operation's purpose, side-effects, reversibility, and authentication requirement. With a well-described schema and annotations indicating idempotency, nothing essential is missing for an agent to call this 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 the schema already fully documents slug, start, and adminKey. The description adds 'start=null to reopen' and 'adminKey from create_event', but these details also appear in the schema descriptions, so little new semantic value is 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 states a specific verb and resource: 'settle on a start time' and clarifies the effect 'locks availability picking and voting'. The 'Organiser only' qualifier and the lock-vs-vote distinction differentiate it from vote_time and submit_availability even without naming them.

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

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

It explicitly limits usage to organisers and requires adminKey from create_event, and explains the re-open behavior via start=null. It doesn't explicitly name alternatives or when not to use it, but the context is clear enough to guide selection.

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 readOnlyHint annotation already signals safety, and the description reinforces this by saying 'Read an event' and 'No key needed,' adding useful authentication context. It also discloses the exact set of returned fields, which goes beyond the annotation's minimal safety signal.

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 dense sentence that front-loads the core purpose and then packs an exhaustive list of return data into parentheticals. Every clause carries information, with no filler or repetition.

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

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

With no output schema present, the description fully compensates by naming every significant returned component: settings, startOptions, participants, ranked top 10, voteOptions, votes, and decidedStart. It also covers the access requirement ('No key needed'), making the tool complete for a single-parameter read operation.

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 the single slug parameter with a pattern and an example, providing 100% schema description coverage. The description does not add parameter-level detail 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 states a clear verb ('Read') and a specific resource ('an event'), then enumerates the precise data returned: settings, startOptions, participants, ranked times, voteOptions, votes, and decidedStart. This clearly distinguishes it from sibling mutation tools like create_event, update_event, and submit_availability.

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 establishes that this is a read-only retrieval operation and adds the practical note that no key is needed. It does not explicitly name alternative tools or state when not to use it, but the read-versus-mutation contrast with the sibling tools makes the intended usage 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 annotations already declare readOnlyHint=true, and the description reinforces this by saying 'Does NOT create anything'. The description adds useful behavioral context beyond annotations: it is an AI parser, it works best with Chinese, and its output should be reviewed before acting. 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 compact and front-loaded: the core function is stated first, followed by the critical safety clarification and a concrete example. Every sentence earns its place, and there is no redundant wording.

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

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

For a simple two-parameter, read-only parsing tool with full schema coverage, the description covers the essential context: what it does, what it does not do, and what to do next. There is no output schema, so a bit more detail about the exact shape of the returned create_event input would be ideal, but the description already says the output is create_event input and instructs the agent to review it.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description adds a clarifying example and the 'Chinese works best' hint, which helps with the text parameter, but it doesn't add substantial parameter-level meaning 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 states a specific verb ('Turn'), a specific resource ('natural-language sentence'), and a concrete target output ('create_event input'). It also explicitly distinguishes itself from create_event by saying 'Does NOT create anything', which separates it from the sibling tool.

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 clearly tells the agent when to use this tool: for natural-language sentences, with a note that Chinese works best. It also gives explicit follow-up guidance: review the result, then call create_event. The example makes the intended usage concrete and understandable.

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 destructiveHint annotation, the description discloses the tie-breaking behavior ('the oldest row with that name when it repeats'), that the vote is removed with the participant, and that adminKey is required. This is meaningful behavioral context 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 two sentences with no filler. It front-loads the key constraints (organizer-only, removes vote) and the tie-break rule, while keeping the whole definition compact.

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, three-parameter destructive tool, the description fully covers permission requirements, the exact deletion behavior, and the duplicate-name rule. No output schema is needed to understand the effect of this operation.

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 removal is by exact name, how repeated names are handled, and where the adminKey comes from, which enriches the parameter semantics beyond the raw 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 uses a specific verb ('remove') and resource ('participant'), and clarifies it also removes their vote. It also specifies organizer-only access, which distinguishes it clearly from the other event-management 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 clearly states who may use the tool (organizer only) and the required credential (adminKey from create_event). It does not explicitly contrast it with alternatives, but none of the listed siblings serve the same removal purpose, so the guidance is adequate.

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 explaining that the same identity overwrites its row and can rename it, that a different identity with the same name becomes a second participant, and that invalid keys are rejected. It also discloses the return value, which is especially valuable because no output schema is present.

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 tightly written sentences cover the core action, the identity semantics, validation, and the return value. Every sentence earns its place, and the most important distinction (identity vs. name) 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 the tool's moderate complexity and the absence of an output schema, the description is complete enough for an agent to call it correctly. It explains the overwrite behavior, participant identity model, validation constraints, and what the response contains.

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 real value by clarifying that identity is the true key and name is not unique, that starts come from get_event.startOptions, and that invalid keys are rejected. This enhances the schema's identity and starts documentation without repeating 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 opens with a specific verb and resource: 'Save (or replace) one person's availability,' and ties the data to get_event.startOptions. It clearly distinguishes this from sibling tools by framing it as availability submission rather than voting, event creation, or participant removal.

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: use this after fetching start options from get_event, and pass an identity token rather than a name. It does not explicitly name alternatives or state when not to use it, but the intended workflow is unambiguous for 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?

Beyond annotations (readOnly=false, idempotent=true, destructive=false), the description discloses several non-obvious behaviors: omitted fields keep current values, endDate takes precedence over days, existing picks are retained, and invalid starts are merely hidden. This exactly covers the update semantics an agent needs to know before invoking.

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 carry the essential permissions, update behavior, conflict rule, and participant effects with no filler. The most important constraint (organiser only) 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 an 11-parameter update tool with no output schema, this is nearly complete: permissions, partial-update semantics, conflict resolution, and downstream effects on picks are all covered. It delegates field-level rules to create_event and does not describe the response shape, leaving a small gap.

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

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

The schema already documents all parameters (100% coverage), so the baseline is 3. The description adds valuable cross-cutting parameter behavior—omitted fields are unchanged and endDate overrides days—and points to create_event for shared field rules, exceeding schema-only information.

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 opens with 'Organiser only: change any event settings', naming a specific action (change) on a specific resource (event) and immediately scoping it to the organiser. It also distinguishes the update semantics from create_event by stating omitted fields persist and picks are preserved.

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 indicates this tool is for changing settings of an existing event and requires organiser credentials, which is strong usage context. It does not explicitly list when-not-to-use or name alternative tools, but the update-vs-create distinction is implied through 'same fields and rules as create_event'.

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 behaviors beyond annotations: it replaces earlier approvals, an empty list clears them, invalid keys produce an error listing current options, and the operation is rejected after an organiser decision. These are not visible in the annotations alone and give the agent a realistic model of side effects.

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

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

The description is front-loaded with the core action, then logically covers replacement, clearing, prerequisites, validation, rejection, and a complete example. Every sentence adds distinct information and the length is appropriate for the tool's semantics.

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 is largely complete, but it does not specify what happens if the optional starts parameter is omitted, even though only slug and identity are required. With no output schema, it also does not describe the success response. These are minor gaps relative to the otherwise thorough guidance.

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 explains slug, identity, starts, and start. The description adds value with a concrete example, explains that 'start' is shorthand for a single-item starts list, and clarifies that identity is the voter identity from submit_availability.

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 clear verb and object: 'set every start one person accepts', and the title 'Approve start times' matches. It also distinguishes this tool from siblings by framing it as approval voting tied to identity and voteOptions from get_event, not creation or decision-making.

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 strong context: the identity must come from submit_availability and have at least one saved start, keys must be from get_event.voteOptions, and calls are rejected once the organiser decided. It does not explicitly name sibling alternatives, but the constraints clearly indicate when and how this tool should be used.

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