Whenna

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

Annotations already declare readOnlyHint=true, and the description adds useful behavioral detail: the result is ranked, blocks are contiguous, and it reports who is free. This goes beyond the annotation and does not contradict it.

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

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

The description is a single clear sentence, front-loaded with the verb and resource, and contains no filler or redundant information.

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

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

For a simple two-parameter read-only tool, the description adequately explains the core purpose and output concept. It could be more explicit about the return format and the meaning of 'top', but overall it is complete enough for an agent to understand the tool's role.

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

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

The schema has no parameter descriptions (0% coverage), so the description needs to compensate. It implies 'id' refers to a plan, but the 'top' parameter is only vaguely tied to 'Ranked' without explicitly stating it controls the number of results.

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

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

The description clearly states the tool's purpose: 'Ranked best meeting times for a plan' and specifies the core output: 'contiguous blocks where the most participants are free, with who is free in each block.' This distinguishes it from siblings like whenna_get_plan or whenna_lock_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?

Usage context is implied by 'for a plan' but there is no explicit guidance on when to use this tool versus alternatives like whenna_get_plan or whenna_plan_next. No exclusions or alternative references are provided.

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

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

No annotations exist, so the description carries the full burden. It discloses non-obvious behavior: wall-clock interpretation in a timezone, recurring plan semantics, and the creator_key's authorization role for locking. While it doesn't enumerate every side effect (e.g., email sends), it provides substantial behavioral context beyond the name.

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, densely packed but every clause earns its place. The most important info (purpose and return values) is front-loaded, with timezone and recurring rules following naturally. No fluff or redundancy.

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

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

For a tool with 11 parameters and no output schema, the description covers the key return values, the creator_key's purpose, and tricky recurrence/timezone behavior. It doesn't address every edge case or error condition, but it provides a solid mental model for a plan-creation tool. The schema handles parameter details, leaving the description to focus on usage nuance.

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%, which sets a baseline of 3. The description adds valuable semantics for the complex 'days' parameter (date vs weekday vs daily vs monthly rules) and clarifies timezone handling. It reinforces and extends the schema's parameter docs, justifying an above-baseline score.

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 ('Create a Whenna plan') and clarifies the output (shareable link, creator_key). It clearly distinguishes itself from siblings like whenna_best_times or whenna_lock_time by focusing on plan creation.

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

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

The description implies when to use the tool (when you need to create a plan) but does not explicitly reference alternatives or exclusions. No guidance is given on when to prefer this over whenna_best_times or whenna_get_plan, so it falls short of explicit usage direction.

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 discloses the detailed return payload including the state enum, who answered, and suggested_next_step, and advises polling between actions. This adds useful behavioral context about its role as a status-checking tool.

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

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

The description is front-loaded with the core purpose and uses a structured list for the payload. While slightly long, it is well-organized and every sentence adds value, including the polling 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?

The description comprehensively covers what the tool returns, including state values and the suggested next step, which is especially valuable given there is no output schema. It sufficiently prepares an agent to interpret and use the response for coordination.

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 only parameter 'id' is fully documented in the schema with a clear description ('the part after /o/ in the link'), so the description does not need to add parameter details. Coverage is 100%, earning the baseline of 3.

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

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

The description clearly identifies the tool as fetching a Whenna plan and enumerates its contents (title, window, availability, best times, locked time, negotiation brief). This distinguishes it from sibling action tools like whenna_create_plan and whenna_lock_time, which mutate state.

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

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

It provides explicit usage guidance: 'Poll this between actions when coordinating,' indicating when the agent should call it. It does not name specific alternatives, but the context implies it is for checking plan state between mutations, which is sufficient.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It discloses the prerequisite (creator_key), the side effect on viewers (all see it as confirmed with add-to-calendar buttons), and the return value (calendar links). It does not mention whether locking is reversible or error conditions, but it covers the key behavioral aspects for a locking action.

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

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

The description is three sentences long, front-loads the primary purpose, and every sentence contributes distinct information: prerequisite, two modes, outcome, and return value. No filler or redundant phrasing.

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 absence of an output schema, the description wisely states the return value (calendar links). It provides enough context for the agent to understand what the tool does and when to invoke it. Minor gaps include lack of error handling or idempotency details, but the essential use-case is well covered.

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 67% (4 of 6 properties have descriptions), and the description compensates by explaining the relationship between parameters (use_best vs day/start) and the origin of creator_key. It adds semantic meaning beyond the raw schema, helping the agent decide which parameters to provide based on the scenario.

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 ('Lock the final time on a plan'), making the tool's purpose immediately clear. It distinguishes itself from sibling tools by focusing on finalization/confirmation rather than listing, creating, or planning, and it clarifies the two modes of operation (use_best vs explicit day/start).

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: it requires the creator_key from whenna_create_plan and explains how to choose between automatic best-time locking or explicit scheduling. While it doesn't explicitly state when not to use this tool or compare to alternatives like whenna_best_times, the context strongly implies this is the final confirmation step after selecting a time.

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

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

With no annotations provided, the description fully carries the behavioral disclosure burden and excels. It discloses that the action replaces previous answers, that the server converts free ranges to slots, that an empty free array records an explicit 'can't make any' (shown as a ✗), and that withdraw:true removes the answer entirely. It also mentions the result reports unapplied ranges and reasons, which is far beyond the minimum.

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. The first sentence states the core action and side effect, the second clarifies important naming guidance and the server conversion, and the third distinguishes the two special cases plus the result reporting. It remains appropriately sized given the tool's complexity and is front-loaded with the most critical information.

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

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

Given the absence of an output schema, the description does enough to set expectations by mentioning that unapplied ranges are reported with reasons. It covers the two major edge cases (empty free and withdraw), clarifies the timezone-conversion behavior, and gives naming guidance. For a tool of this complexity, the description is complete and self-sufficient.

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

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

The schema covers 75% of parameters with basic descriptions, but the description adds crucial semantics: 'name' should be the participant's human name for group recognition, 'free' as an empty array means an explicit 'can't make any', and 'withdraw' overrides the free array to remove the answer. These semantics are not expressed in the schema and materially improve invocation correctness.

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: 'Set a participant's free times on a plan', which clearly distinguishes this from siblings like whenna_get_plan or whenna_lock_time. It also immediately clarifies the key behavioral nuance that this replaces the participant's previous answer, making the tool's purpose unmistakable.

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 and even contrasts the two modes (empty free array vs withdraw:true), which steers the agent toward the correct usage. It doesn't explicitly name alternative sibling tools or say 'use when...', but the context is strong enough to differentiate it from the other tools. Lacking explicit exclusions prevents 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?

With no annotations available, the description fully carries the transparency burden. It discloses email side effects, link behavior, idempotency, the need for creator_key, and the return of a new creator_key for locking the new time—all beyond a basic purpose statement.

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 yet every sentence adds operational value—purpose, effects, authorization, return value, and idempotency. It is front-loaded and avoids filler despite covering a complex tool.

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 mutating tool with email side effects and no output schema, the description covers return values, side effects, and idempotency well. It does not address edge cases like missing finished plans or absent locked weekdays, but the core usage is complete enough.

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

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

The schema has zero descriptions, and the description only partially compensates: creator_key is explained as required and returned for locking, but id is only implicitly the identifier of the finished plan. It is inferable but not explicitly documented.

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 operation: start the group's next plan from a finished one, and details concrete effects (cloning setup, proposing dates, linking old→new, emailing). This clearly distinguishes it from the sibling create_plan by framing it as a successor-cloning 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 intended scenario is clear: use when a finished plan exists and you want to carry its setup into the next occurrence, with idempotent behavior if a successor already exists. It does not explicitly name alternatives or say when not to use it, but the 'from a finished one' condition is enough context.

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

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

Beyond the idempotentHint annotation, the description discloses specific side effects: attaching Whenna's encrypted video room and automatically adding the room link to everyone's calendar. It also notes the creator_key requirement and the mutual exclusivity of place and video room. No contradiction with the 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?

The description is two sentences, front-loaded with the core action. Every clause adds value: the location option, the video_call option, its calendar side effect, mutual exclusivity, and the auth requirement. 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?

For a simple setter with 4 parameters and no output schema, the description covers the main behavior, the two modes, and the auth requirement. It does not mention that omitting both location and video_call is likely invalid, but the schema's optionality makes that a minor gap. Overall, it is sufficiently complete for the tool's 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 covers location and video_call with descriptions, and the description adds extra meaning about video_call's behavior and the exclusivity relationship. However, id and creator_key have no schema descriptions nor are they explained in the tool description beyond 'requires creator_key', leaving their purpose ambiguous.

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 'Set where the group meets', a specific verb+resource that clearly states the tool's function. It further distinguishes the two modes (place name or video_call) and signals exclusivity, which differentiates it from sibling tools like whenna_best_times or whenna_lock_time that address other aspects.

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 tool to set the group's meeting location. It explains the two options and the required creator_key, but does not explicitly state when to prefer this over sibling tools or exclude cases. The mutual exclusivity note is a useful intra-tool guideline.

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