Mooi

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

The description usefully rules out two side effects (no email sent, no change created), which goes slightly beyond the annotations. However, annotations declare destructiveHint=true and openWorldHint=true, and the description never explains what is destroyed, whether the acknowledgment is reversible, or what external state is touched. For a mutation tool with destructive and open-world hints, that is a significant unexplained area.

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

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

Two short sentences, front-loaded with the action and followed by the disambiguating exclusions. There is no filler and nothing redundant.

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

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

This is a five-parameter mutation tool with no output schema, no parameter descriptions, and destructive/open-world annotations. The description covers roughly one parameter and one side-effect caveat, leaving the identity parameters, the idempotency key, and the destructive semantics undocumented.

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

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

Schema description coverage is 0% for all five parameters, so the description must carry the burden and largely does not. 'Up to a version' gives the version parameter meaning as a high-water mark, but eventId, participantId, requestId and agent are never mentioned, leaving the agent to guess whether requestId is an idempotency key and whether agent is a label or an identity.

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

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

The description gives a specific verb and resource: record that changes have been read, up to a given version. The negative clarifications ('does not send email or create a new change') sharpen the boundary against what a naive reader might assume. It does not name a sibling such as get_changes, so it falls short of full sibling differentiation.

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

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

Usage is only implied: an agent can infer this marks changes as seen after reading them, presumably following get_changes. There is no explicit statement of when to call it versus when not to, and no mention of prerequisites such as having read the changes first.

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

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

Annotations already declare this is a non-read-only, open-world, idempotent, potentially destructive write, so the safety bar is partly covered. The description usefully adds that it returns a direct comment link, but it says nothing about idempotency keying (requestId), permission requirements, or why the operation is flagged destructive — a notable silence for a mutation tool.

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

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

Three short sentences, front-loaded with the action and followed by the two facts an agent most needs (attachment mechanism, return value). No filler, though the extreme terseness leaves the parameter gaps unaddressed.

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

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

For a tool with six parameters, four of them required, zero schema descriptions, and no output schema, the description is under-specified — notably leaving the required eventId/participantId/requestId unexplained and omitting any note on idempotency or destructive semantics.

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

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

Schema description coverage is 0% across 6 parameters, so the description carries the full burden and it only explains one: questionId's discussion-attachment role. eventId, participantId, requestId, body, and agent are left entirely unexplained despite requestId strongly implying an idempotency key.

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 concrete verb+resource pair ('Post a message or answer a question') and clarifies the discussion-attachment behavior via questionId. It clearly implies a write-to-thread operation distinct from siblings like ask_question or decide_question, though it never names those alternatives explicitly.

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

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

Usage is only implied: the reader infers 'use questionId to answer an existing discussion' and 'omit it to post a plain message.' There is no explicit when-to-use/when-not guidance and no routing to sibling tools such as ask_question or vote.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the description should explain the surprising parts — yet it adds nothing. It never mentions that the caller must be a participant, that adding an option may have side effects on existing votes, or why an append operation is flagged destructive.

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 tight sentence with no filler and the key noun front-loaded. Brevity is appropriate, though it is under-specified rather than genuinely concise.

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 destructive, idempotent mutation requiring five identifiers/strings with zero schema documentation and no output schema, one sentence is far below what an agent needs. It should at minimum explain the identifier roles and the destructive/participant constraints.

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

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

Schema description coverage is 0% across six parameters, so the description carries the full burden and mostly fails: eventId, participantId, questionId, requestId, and agent are utterly unexplained. Only 'label' gains any meaning from the city/restaurant examples, and even that is indirect.

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 (add an option) scoped to 'an open question', with concrete examples of what an option looks like. It is clearly distinguishable from siblings like ask_question, decide_question, and vote, though it does not explicitly name those 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?

The only usage signal is the phrase 'open question', which implies a precondition but is never explained. Nothing says when to call this instead of vote, decide_question, or propose_date, nor what happens if the question is closed.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is carried by structured data. The description adds useful behavior about the parent/child linkage and about empty options producing a discussion. It says nothing about what requestId does for idempotency, what side effects (notifications to participants) creation triggers, or what the destructiveHint means in this context, leaving real gaps.

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

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

Three short sentences, front-loaded with the core capability before the workflow detail. Nothing is redundant. It is slightly compressed to the point of being telegraphic ('kind city', 'parentId pointing to'), which costs a little readability.

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?

This is a mutation tool with 8 parameters, zero schema description coverage, and no output schema, so the description is the only source of semantics. It covers the question-creation workflow but leaves the identity/plumbing parameters (eventId, participantId, requestId) and the idempotency behavior completely unexplained — an agent cannot confidently construct a valid call without external knowledge.

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

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

Schema description coverage is 0% across 8 parameters, so the description must carry all semantic weight. It explains only three things: kind values city/restaurant, parentId's role, and the empty-options convention. eventId, participantId, requestId, agent, and title — including four required parameters — are never characterized, so an agent must guess their meaning from names alone.

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

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

The description opens with a specific verb and resource pair: 'Ask a question or create a poll.' That distinguishes it from siblings such as add_poll_option, vote, and decide_question, which operate on an existing question rather than creating one. It does not explicitly name those siblings as alternatives, keeping it just 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?

It gives concrete sequencing guidance — 'Use kind city first, then restaurant with parentId pointing to the city question' — which tells the agent how to chain calls for the two-phase flow. It also states the empty-options case means an open discussion. There are no explicit when-not-to-use conditions or named alternative 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?

The retry/idempotency-key contract ("reuse it for uncertain retries, including across HTTP/MCP clients") is genuinely valuable context that annotations do not convey. However, annotations declare destructiveHint=true and openWorldHint=true, and the description never explains what is destructive here (e.g., host notification emails, external visibility) nor mentions the emailAccess side effect; the personalUrl/url sentence describes outputs the schema does not declare.

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?

Only three sentences and correctly front-loaded with the retry contract, which is the highest-value detail. But the middle sentence is spent on personalUrl/url fields that do not exist as inputs, consuming scarce space that could have documented timezone, agent, or emailAccess.

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

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

For an 8-parameter, non-read-only creation tool with no output schema and zero schema descriptions, the definition answers only a fraction of what a caller needs: how to retry safely and that email is required. Six parameters and the meaning of destructiveHint=true are left entirely unexplained, and one sentence points at parameters the schema does not have.

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

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

Schema description coverage is 0% across 8 parameters, so the description must carry the burden, yet it only explains requestId and confirms email is required. The remaining parameters — title, timezone, name, agent, description, emailAccess — are undocumented, and it references 'personalUrl' and 'url', which are not in the input schema at all, which is actively misleading for a caller building the payload.

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?

"Create an event and register its host" gives a specific verb plus two concrete resources (event and host), so an agent knows exactly what side effect to expect. It does not explicitly distinguish itself from update_event or get_event, which are present in the sibling list, so routing still requires inference.

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 real operational rules: reuse requestId for uncertain retries, keep personalUrl for the host, share plain url with invitees, email is required for updates. These are useful usage constraints, but there is no guidance on when to create versus update an existing event, nor any prerequisites or exclusions relative to 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?

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds genuinely new behavioral policy: agents may decide without human approval, must state unresolved assumptions, must not claim unanimity from vote counts or silence, and must reopen on veto. That is substantive governance context. It still does not say what happens to the previously recorded decision when overwriting, or what reopening actually resets.

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 action is front-loaded in the first sentence, and the following sentences are short policy clauses rather than filler. The veto sentence is slightly tangential but earns its place by explaining the reopen trigger.

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 destructive, open-world mutation with 7 undocumented parameters and no output schema, the description covers the social policy well but leaves the mechanics thin. An agent still lacks the id formats, who participantId should be, and what a recorded decision displaces.

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

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

Schema description coverage is 0% across 7 parameters, so the description bears the full burden and it only touches two of them: 'decision' is glossed as 'city, restaurant or other detail' and 'reopen' is mentioned topically. eventId, participantId, requestId, questionId, and agent are entirely unexplained, and the reopen mechanics (what it clears, whether decision is then required) are not stated.

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-resource pair: 'Record the current choice of city, restaurant or other detail, or reopen a question.' It distinguishes itself from siblings like vote and ask_question by framing the tool as the terminal action on a question. It stops short of naming alternatives explicitly, so it is clear but not sibling-routing.

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 a clear condition for use ('Agents may decide using the group's responses and discussion without separate human approval.') and a clear condition for the reopen path (a human veto). It never says when to prefer vote, add_comment, or ask_question, so the alternatives remain inferential.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so "never emails participants" largely restates that safety profile, though it is a concrete reassurance. The genuinely additive behavior is the at-least-once delivery implication of "save nextVersion only after processing" and the exclusive cursor boundary, but the description never states what the response returns or where nextVersion comes from, which matters because there is no output schema.

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

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

Three short sentences, front-loaded with the core fetch semantics, then the cursor-safety rule, then polling cadence; nothing is padding. The telegraphic style leaves the connection between "nextVersion" and the request parameters implicit, costing some clarity for no real size saving.

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?

Annotations and the input schema are lean, but this tool's contract is a cursor loop, and the description covers the two critical loop rules: the exclusive lower bound and not advancing the cursor before processing. The remaining gap is the return payload shape (change entries plus nextVersion), which is not in an output schema and must be inferred.

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

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

Schema description coverage is 0%, so the description carries the burden and only partially meets it: "strictly after sinceVersion" clarifies the exclusive boundary (schema only shows an integer defaulting to 0), but eventId is left entirely unexplained despite its unusual 48-hex-character pattern. The default value of sinceVersion and the meaning of an absent/non-advancing cursor are also unaddressed.

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

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

"Fetch changes strictly after sinceVersion" gives a specific verb (fetch) and a scoped resource (changes since a cursor), and the exclusivity qualifier is precise. It never names the resource domain (event changes) nor distinguishes itself from near-siblings like get_event, get_channel_update, or acknowledge_changes, so an agent must infer what kind of "changes" are returned.

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 polling instruction (every 300 seconds when email monitoring isn't available) and the cursor-advance rule ("Save nextVersion only after processing") together describe a concrete usage pattern an agent can follow. What's missing is routing guidance: no statement about when to use get_event or acknowledge_changes instead, and no explicit when-not-to-use condition.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and the description is consistent with them. It adds genuinely useful behavior beyond annotations: the exclusion of already-recorded deliveries, the shouldSend gate, and the required follow-up recording step. It omits details like what the built message payload contains or how sinceVersion interactively filters, keeping it below a 5.

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

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

Four short sentences, each carrying a distinct constraint: what is built, what is excluded, what gate controls sending, and who performs the actual send. Front-loaded with the core action and zero padding.

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

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

No output schema exists, and the description helpfully surfaces shouldSend as the decision signal the agent must read. For a 3-parameter read-only builder with full annotation coverage, the main missing piece is the shape of the returned message/link and the meaning of sinceVersion.

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

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

Schema description coverage is 0% across 3 parameters, so the description must compensate. It conveys the channel domain (WhatsApp/Signal/email) and hints that already-recorded deliveries can be excluded, which plausibly maps to sinceVersion, but eventId and the version semantics themselves are never explained. Partial compensation only.

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

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

The description gives a specific verb+resource: "Build a linked message" for WhatsApp, Signal or email, with a scope qualifier excluding already-recorded deliveries. An agent can distinguish it from record_channel_update and set_channels. It stops short of naming a sibling directly, so 4 rather than 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?

Explicit when/how/when-not: gate sending on shouldSend being true, then send via "your authorized channel connector and record delivery afterwards." It also explicitly states what this tool does not do ("does not send anything"), leaving no ambiguity about the handoff to the delivery recorder.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds a genuine data-scope disclosure beyond that: emails are private and never returned, which tells the agent not to expect participant addresses in the response. It does not cover visibility/permission limits or whether activity is truncated.

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

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

Two short sentences, no filler, with the returned resource list front-loaded and the privacy caveat placed after it. Slightly terse given the strict identifier requirement, but 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, enumerating the returned sections is valuable and the privacy note is a real constraint. However, for a tool whose only parameter has an unformatted 48-hex-character pattern and no documented error behavior for a bad ID, an agent is left to guess the identifier's provenance.

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

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

There is one required parameter, eventId, with 0% schema description coverage and a strict ^[a-f0-9]{48}$ pattern that is never explained. The description says nothing about how to obtain or format the identifier, so it fails to compensate for the coverage gap.

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

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

Specific verb plus an enumerated payload: 'Read the event, dates, availability, questions, decisions and activity.' That makes it distinguishable from mutation siblings like update_event, though it does not explicitly distinguish itself from other read siblings such as get_changes or get_channel_update.

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 this is the general read operation but never states when to choose it over get_changes, get_channel_update, or the narrower question/date reads. No prerequisites, no exclusions, no alternative routing.

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

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

The description adds consent context and explains emailAccess, but with destructiveHint=true it should disclose what registration changes and whether it is irreversible. It also does not address idempotency or open-world behavior already declared in annotations.

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

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

The description is short and front-loaded, with no filler. The three sentences are readable and each contributes something, though the emailAccess sentence could be tied more explicitly to the agent parameter.

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 six-parameter, four-required, destructive registration tool with no output schema and no schema descriptions, the description is too sparse. It omits most required parameters and does not explain the destructive side effects or what a successful registration produces.

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

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

Schema description coverage is 0%, so the description must compensate. It explains only email and emailAccess, leaving eventId, name, requestId, and agent undocumented, including the required requestId format and eventId pattern.

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 action: registering yourself or the person you represent, with their email. It is clearly a participant-registration tool, though it does not explicitly mention the event or distinguish itself from nearby tools like update_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?

It implies when to use it by telling the caller to register themselves or someone they represent, and adds a consent constraint against registering others without permission. It does not name alternatives or explain when another sibling tool would be more appropriate.

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

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

Annotations declare destructiveHint=true, idempotentHint=true and openWorldHint=true; the description adds real context by explaining timezone-based display and the availability-verification caveat. It never addresses the most consequential annotation signal, however: why adding an option is flagged destructive (e.g. whether existing proposed options are replaced or overwritten), nor how idempotency is achieved via requestId.

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

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

Two compact sentences with the core operation stated first and the constraints folded in afterwards; very little waste. The timezone sentence is slightly cryptic (which entity's timezone?) but it 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 seven-parameter, non-read-only, destructive-flagged mutation with no output schema, the description leaves major gaps: parameter meanings, the destructive side effects, and what the tool returns (a created option, an id, an error on conflict). It covers timezone and availability caution but not enough for confident invocation.

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

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

Schema description coverage is 0%, so the description must explain all seven parameters, yet it only touches start/end formatting (which the schema's date-time format and regex already enforce). eventId, participantId, requestId, agent and label are entirely unexplained, leaving the agent to guess that requestId is an idempotency key and label is the option's display 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 opens with a specific verb and object ("Add a date option with ISO 8601 start and end"), which tells an agent this mutates an event's date options rather than voting or removing them. It is close to sibling-distinguishing (remove_date, vote), but never names the alternatives, 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?

"Check accessible calendars and propose suitable options autonomously" gives behavioral direction, and "do not claim unverified availability as certain" sets a confidence rule. However, there is no statement of when to call this versus vote, set_availability, or remove_date, and no preconditions such as required permissions or that the event must exist.

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

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

Annotations already declare a non-read-only, idempotent, open-world, destructive operation, so the agent knows the safety profile. The description adds a useful side-effect clarification ("Does not trigger more emails") and the confirmation precondition, but says nothing about what state is mutated, whether duplicates are tolerated, or what errors look like — notable given the destructiveHint.

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

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

Three short sentences, front-loaded with the purpose, then the precondition, then the side-effect caveat. 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?

This is a five-required-parameter mutation tool with no output schema and a destructive annotation, yet the description explains none of the identifiers or the version/requestId semantics needed to call it correctly. The precondition and email caveat are good, but the definition is not complete enough for a tool of this complexity.

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

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

Schema description coverage is 0% across six parameters, so the description carries the full burden and provides no meaning for eventId, participantId, requestId, channel, version, or agent. An agent must infer the format constraints (48-hex eventId, UUID participantId, 8-char minimum requestId, bounded version) entirely from 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 and resource ("Record a successful external message delivery") that clearly identifies this as a write-side completion record. It does not, however, distinguish itself from the sibling get_channel_update, which an agent could easily confuse with it.

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

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

"Only call after your channel confirms the message was sent" gives an explicit precondition for invoking the tool. There is no statement of when not to call it and no named alternative, so it stops short of full routing guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is largely covered. The description adds a meaningful business rule about confirmed dates, but it does not describe side effects, authorization requirements, or what happens to related participants or proposals.

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 definition is two short sentences with the action front-loaded and no wasted wording. The precondition follows immediately and is 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?

For a destructive mutation with five parameters, no output schema, and 0% schema description coverage, the description is too thin. It states the key confirmed-date constraint but leaves parameter meanings, error behavior, and return expectations undocumented.

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

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

Schema description coverage is 0%, and five parameters are present, including required eventId, participantId, requestId, and dateId. The description only indirectly implies dateId and provides no meaning for the other identifiers or the optional agent parameter. It therefore does not compensate for the schema's lack of parameter documentation.

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 and resource: "Remove a proposed date." It also scopes the action to proposed dates rather than confirmed dates, which helps distinguish it from related date workflows. It does not explicitly name sibling tools, so it falls short of the top score.

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 gives a clear precondition: a confirmed date cannot be removed until it is changed or the event is reopened. That is useful when-not-to-use guidance. It does not name the specific tools to use instead, such as update_event or propose_date.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the description's increment is the partial-update rule ("Omitted dates remain unchanged"), which is genuinely useful for a destructive write. It does not explain why the operation is flagged destructive (overwriting an existing vote), nor any permission or rate constraints, so the added behavioral context is real but thin.

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

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

Four sentences, each carrying actionable content, with the core operation front-loaded before the autonomy and update guidance. The final "omitted dates remain unchanged" sentence is well placed; nothing is padding, though "Change responses when…" mildly restates the opening verb.

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 destructive, open-world write with four required identifiers and no output schema, the description covers intent and partial-update semantics but omits what the identifiers refer to and what a successful call returns or how failures surface. Adequate to attempt a call, not complete enough to call confidently with unfamiliar IDs.

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

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

Schema description coverage is 0% across 5 parameters, so the description carries the full burden. It explains only the `responses` array in spirit ("one or more proposed dates", yes/maybe/no) and says nothing about `eventId`, `participantId`, `requestId`, or `agent` — the latter two are especially opaque given requestId's length bounds and agent's empty-string default.

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 set ("Set or change") and a specific resource ("your yes/maybe/no response to one or more proposed dates"), which clearly frames a per-date RSVP operation. It does not, however, differentiate itself from the sibling `vote` tool, leaving a plausible ambiguity an agent must resolve on its own.

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 concrete operating guidance: check accessible calendars, respond autonomously without per-vote approval, use "maybe" for uncertainty, and re-vote when the human vetoes or circumstances change. There is no explicit when-not-to-use clause or pointer to `vote`/`propose_date` as alternatives, which keeps it below a 5.

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

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

The description usefully discloses that no messaging is sent and that these values are labels, which is real context beyond the annotations. However, annotations declare destructiveHint=true and idempotentHint=true, and the description never says whether existing channels are replaced wholesale, merged, or cleared, nor what gets destroyed by the call.

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

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

Three short sentences, front-loaded with the purpose, and each adds a distinct idea (what it is, what it is not, who sends messages). Slightly clipped rather than padded, which is the right failure mode here.

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?

This is a destructive, idempotent mutation with five parameters, a nested channel array, zero schema descriptions, and no output schema. The description omits replacement/destruction semantics and parameter meanings, so an agent cannot confidently predict the effect of the call from the definition alone.

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

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

Schema description coverage is 0%, so the description must carry the load; it does clarify the semantics of the channels/label values ('labels for participants' agents, not credentials'), which is meaningful. But eventId, participantId, requestId, and the agent field receive no explanation, leaving half the parameters undocumented in both the schema and the 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 verb 'Set' plus 'channels' is specific enough to name the object, and the follow-up clarifies that channels are labels rather than integrations. But 'where the group communicates' is fuzzy about whose channels (a participant's) and about scope relative to siblings like get_channel_update and record_channel_update, which are never referenced.

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?

There is an implied workflow hint ('Agents prepare updates and use their own authorized messaging tools'), but no explicit when-to-use, when-not-to-use, or alternative tool guidance. Nothing tells the agent whether to call this versus get_channel_update or record_channel_update, both of which appear adjacent.

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

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

Annotations already declare destructive, idempotent, and open-world behavior, so the description's job is lighter: it adds the approval model (agents may confirm without per-step human approval), the precondition that confirmation requires a proposed date, and the human veto path. That is meaningful context beyond the annotations, though it says nothing about what a destructive update overwrites.

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 editable fields are front-loaded in the first sentence and the approval rules follow. It is dense but nearly every clause carries information; the only softness is the compressed phrasing around 'coordinate alternatives,' which is more workflow narrative than invocation guidance.

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 destructive, idempotent mutation with 10 parameters at 0% schema coverage and no output schema, the description covers the approval and veto semantics well but omits the identities required to call it (eventId, participantId, requestId) and what a destructive update affects. Adequate for the workflow, incomplete for invocation.

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

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

Schema description coverage is 0% across 10 parameters, so the description must compensate. It covers title, description, timezone, location, and status, and implicitly ties confirmedDateId to confirmation, but leaves eventId, participantId, requestId, and agent entirely unexplained, so half the surface remains undocumented.

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 first sentence gives a concrete verb plus the exact editable fields (title, description, timezone, location, status), which clearly separates it from siblings like propose_date or create_event. It does not explicitly name which sibling handles non-update flows, but the scope is 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 gives workflow guidance for two cases: agents confirming a proposed plan without per-step approval, and humans vetoing by setting status to planning and re-coordinating. It never states when to use update_event instead of propose_date, remove_date, or create_event, so routing to alternatives is left implicit.

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

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

Annotations already declare this is a mutation with destructiveHint=true and idempotentHint=true, so the safety profile is carried by structured data. The description adds only a narrow note about emails not being triggered by reads/acknowledgements; it never explains what a destructive change means here (e.g. whether disabling email access is reversible) or why eventId/participantId/requestId are required for what is framed as changing 'your' preferences.

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

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

Two short sentences with the field list front-loaded and no filler. The trailing email note is slightly tangential to the main enumeration but is relevant and brief.

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 seven parameters, three of them required identifiers, a destructive mutation hint, and no output schema, the description should say more about the identifier parameters and the consequences of the change. It is adequate for the user-facing field list but incomplete for correct invocation.

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

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

Schema description coverage is 0% across 7 parameters. The description covers roughly four of them by name, but leaves eventId, participantId and requestId (apparently an idempotency key, given idempotentHint) completely unexplained, so an agent must infer required-parameter meaning from names alone.

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

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

The description names a specific verb ('Change') and enumerates the updatable fields (display name, agent, email monitoring mode, email notification preference), which maps cleanly onto the name, agent, emailAccess and notifications properties. It does not explicitly differentiate itself from update_event or set_channels, but the purpose is 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?

There is no statement of when to use this tool versus siblings such as update_event or set_channels, and no prerequisites are described. The only contextual remark ('Reading and cursor acknowledgements do not trigger emails') is a behavioral aside, not usage 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 annotations already declare destructiveHint=true and idempotentHint=true, and the description supports rather than contradicts them: 'Replace your votes' explains the replacement semantics and 'an empty array clears your votes' spells out the destructive edge case. It also discloses the consequence boundary, that votes do not automatically decide a question, which is behavioral context the annotations cannot express. It stops short of describing error conditions, required permissions, or the response, keeping it below a 5.

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

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

The action and its option semantics are front-loaded in the first two clauses, and the remaining sentences each deliver distinct operational guidance: autonomy to vote, the reopen-decided-question precondition, and the boundary against decide_question. There is no filler or restated name/title.

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 six-parameter mutation tool with full annotation coverage and no output schema, the description covers the workflow around voting, the destructive clearing case, and the required sibling-tool handoff. The remaining gap is parameter-level detail for the identifier fields, which the zero-coverage schema leaves entirely on the description's shoulders.

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

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

Schema description coverage is 0% across six parameters, so the description carries the load, but it only adds meaning for optionIds (select all acceptable options, empty array clears). The identifier parameters stay unexplained, and requestId, with a bare 8-to-100-character constraint, is an undocumented idempotency-like key that an agent must guess at, as is agent. With five of six parameters unaddressed, it does not compensate for the coverage gap.

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, 'Replace your votes on a question', and immediately clarifies the scope of the operation with 'Choose all acceptable options; an empty array clears your votes.' It also distinguishes itself from the sibling tool decide_question, which is named explicitly, so an agent can separate voting from deciding without opening a schema.

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

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

Guidance is explicit on both sides of the decision: when to use this tool (casting or revising votes autonomously from known preferences), what it does not do (it does not decide the question), and which alternative to reach for (decide_question, both to reopen a decided question before changing votes and to record the selected plan). That exchange of when and when-not is unusually complete.

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