Daycal

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

Annotations already establish readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds meaningful behavior beyond that: the Customer Portal link is null when the agent's access does not include billing, which discloses a conditional permission-scoped result. With no output schema, this field list also serves as the return-value contract, adding real value.

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 sentence that front-loads the most important returned field (current plan) and packs the remaining outputs plus the null-condition caveat without any filler.

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

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

For a parameterless read-only tool with no output schema, the description does the job of documenting the return payload and the conditional-null case. It does not cover things like caching, rate limits, or error behavior, but nothing essential for correct invocation is missing.

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

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

The tool takes zero parameters, so the baseline is 4. There are no arguments whose semantics need explaining.

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 enumerates exactly what the tool surfaces: current plan, renewal/expiry date, plan prices, and a Customer Portal link. Combined with the name and title it is unambiguous, though it never states an explicit verb or differentiates itself from siblings beyond the domain being billing rather than calendars or agents.

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 indication of when to call this versus alternatives, nor any prerequisites or triggering conditions. With zero parameters the decision surface is small, but the description offers no usage context at all.

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 safety is covered. The description adds genuine behavioral content by enumerating exactly which factors the explanation reports (overlap events with their isBusy result, buffers, minimum notice, caps), which tells the agent what the diagnostic actually evaluates.

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 front-loaded sentence with a colon-delimited list of return facets. Zero padding and the core purpose comes first. Slightly telegraphic, but every clause 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?

There is no output schema, so the description carries the burden of describing what comes back, and it largely does by naming hours, overlapping events/isBusy, buffers, minimum notice, and caps. It omits the resolution ordering or shape of those results, but an agent has enough 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 description coverage is 100%, so both parameters (time as ISO 8601 instant, event_type slug) are already fully documented in the schema. The description adds no syntax, format, or constraint detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource (explain a time's bookability) and enumerates the diagnostic facets it reports: hours, overlapping events with isBusy, buffers, minimum notice, caps. An agent immediately knows what it gets back. It does not, however, distinguish itself from the sibling 'preview', which could plausibly cover similar ground.

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 'why a time is or is not bookable' framing implies a diagnostic/verification use case, but there is no explicit when-to-use statement, no prerequisites, and no pointer to the likely-overlapping sibling 'preview'. Usage is inferable rather than stated.

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

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

Annotations cover only safety hints (readOnly, openWorld, non-idempotent), while the description supplies the behavior that actually matters: the payload is delivered to the owner's email, never returns to the caller, the link lives 24 hours behind a browser identity confirmation, and the limit is 5/day with a 429 + retryAt on the sixth. It also explains why idempotentHint=false is true in practice.

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?

It is one dense paragraph but front-loaded with the purpose, and nearly every clause carries operational weight (delivery target, expiry, rate limit, follow-up instruction). The parenthetical inventory of exported entities is long but legitimately scopes the request.

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 input params and no output schema, the description must carry the full load, and it does: it explains what is exported, where it goes, what the caller receives back, how long the link lasts, and how to handle the rate limit. An agent can call this and interpret the result without any other source.

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?

With zero input parameters the baseline is 4, and there is nothing to disambiguate. The description goes further by documenting the three response fields (sentTo masked, expiresAt, relay message), which substitutes for the absent output schema rather than the input 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 states a specific verb and resource ('Email the owner a link to download a full copy of their Daycal data') and enumerates exactly what the export contains. It is unmistakably distinct from every sibling, all of which are list_/get_ readers that return data to the caller.

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 an explicit trigger ('Call it when the owner asks for their data'), an explicit follow-up ('then tell them to check their email'), and an explicit when-not ('ask again only if the owner lost the email'), plus the rate-limit path. No alternative tool competes for this job, so nothing is left to inference.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real behavioral context beyond that: the return is copy-pasteable expressions keyed per calendar, and the 'holidays: true' calendars must be placed in daysOff rather than calendars, which is a non-obvious semantic rule.

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 dense sentences with the core purpose front-loaded and the holidays caveat following. No filler, though the holidays sentence packs two instructions that could be split for 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?

With no parameters and no output schema, the description is the only guide to the return value, and it does describe the content (expressions per calendar) and a key edge case. It could say whether the result is a list or a map keyed by calendar name, but it is sufficient to call and use 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?

The tool takes zero parameters, so the schema has nothing to document and the baseline for this dimension is 4. There is no parameter syntax the description needs to compensate for.

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 resource and the concrete output form: stdlib expressions for rules.js, one per calendar, with an inline example. This is clear enough to distinguish it from list_calendars, though it never names that sibling or explicitly contrasts the two.

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 implied through the destination of the output (rules.js) and the holidays/daysOff rule, which tells the agent how to act on holiday calendars. However, there is no explicit when-to-use-vs-list_calendars guidance or stated prerequisites.

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 closed-world, so the safety profile is covered. The description adds the triggers/scope of failure content, but 'Recent' is left undefined — no time window, no cap on how many failures return, no indication of rate limits or logging prerequisites.

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, zero filler. The return content is front-loaded and the usage trigger follows immediately, with nothing redundant with the 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?

With no parameters and no output schema, the description carries the return-value burden well by naming the failure records and their trigger fields. The undefined recency window is the only real omission for an agent deciding whether this call will surface the failure it cares about.

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

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

The tool takes zero parameters, so there is nothing for the schema to describe and no semantic work for the description to do. Baseline 4 applies; the scope limitations that a hypothetical filter parameter would carry are instead partly addressed by the 'Recent' wording.

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 resource and return content: recent rules.js failures plus the event or day that triggered each. That is far more useful than the name 'get_errors' alone. It doesn't explicitly differentiate from the sibling get_logs, which is the main gap.

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?

"Read this when a slot looks wrong" gives a concrete diagnostic trigger, which is real when-to-use guidance rather than an implied generic 'get errors'. It stops short of naming an alternative (e.g. get_logs) or stating when not to reach for it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact beyond the annotations: the result is capped at the last 500 entries. It does not say ordering, staleness, or whether entries are 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?

A single compact sentence with the scope and the entry cap front-loaded. It is efficient, though the absence of a verb makes it slightly less self-contained than it could be.

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

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

With no output schema and no parameters, the description carries the burden of explaining the return value, and it only partly does: it gives the count cap but not the entry fields, ordering, or time window. Adequate but with a clear gap for a log-inspection tool.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify beyond the fixed scope of 'the owner's' log.

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 resource (the owner's request log) but is a noun phrase with no verb, and it does not differentiate from the sibling get_errors, which an agent could easily confuse with a log-retrieval tool. An agent can infer what comes back, but the purpose is not sharply stated.

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 when-to-use guidance, no mention of the sibling get_errors as an alternative, and no conditions under which this tool should be preferred. Usage must be entirely inferred from the name.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is low. The description adds one genuinely useful trait — returned content has links pointing at this server — but says nothing about size, truncation, or what the reference files contain.

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 what is returned and followed by the audience condition. No filler, though the phrasing is slightly elliptical ("The daycal skill's SKILL.md...").

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 a single optional enum parameter, an explicit audience, and no output schema required, the description covers enough for an agent to call it correctly. The one gap is that it never enumerates what the five reference files are for, leaving the enum names to speak for themselves.

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% and the single enum parameter is fully documented in the schema, so baseline 3 applies. The phrase "or one of its reference files" gestures at the parameter but adds no semantics beyond the enum already in the schema.

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

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

The description states the concrete resource returned — the daycal SKILL.md or one of its named reference files — which separates it from siblings like get_types, get_calendar_refs, or explain. It is clear but relies on the title for the explicit verb and doesn't fully differentiate the reference-file variant from other doc-style tools.

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?

"For agents that cannot install skills" gives a clear audience/condition for when this tool is the right choice. It stops short of naming an alternative for agents that *can* install skills, so the routing guidance is one-sided.

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 establish read-only, idempotent, non-destructive, closed-world behavior. The description adds real context beyond that: that it is a bootstrap call, that it returns a pointer to the signing secret via get_webhook_secret, and that supplying the installed skill version triggers an outdated check. No auth/rate-limit details, but the added behavioral value is genuine.

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 imperative opener is correctly front-loaded. However, the middle clause describing Daycal's product ("a page where people book time with them that matches their real week (trips, holidays, cutoffs, focus blocks, limits, several calendars)") is marketing framing that does not help an agent select or invoke the tool, and it bloats an otherwise dense paragraph.

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

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

With no output schema, the description must describe the return payload, and it does so thoroughly by enumerating each artifact. That is the key completeness requirement here. It is slightly less complete about ordering/dependency with the sibling skill tools, but nothing essential is missing for calling 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 coverage is 100% and the single parameter is optional, so the schema already carries the baseline. The description nonetheless adds effect semantics the schema does not state — that passing the version causes the server to tell you whether it is outdated — which is exactly the kind of meaning a schema cannot convey.

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 and enumerates the concrete artifacts returned (daycal.d.ts, stdlib reference with examples, starter rules.js, skill version, signing-secret pointer, plans/prices). The purpose is legible, but bundling types + reference + version check + pricing into one call muddies the single-resource framing, and no sibling (e.g. get_skill) is named to differentiate.

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?

"Call this first, every session" is explicit and unambiguous about timing, which is rare and valuable. It stops short of the 5 bar because it never names an alternative or a when-not condition relative to siblings like get_skill or get_calendar_refs.

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 closed-world, so the safety burden is covered. The description adds real value beyond them: it reports that results carry a name and last-use value, and that a 'current' marker identifies the caller's own client — non-obvious output semantics for an otherwise opaque read.

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 dense sentence with no filler, and the key scoping qualifier (OAuth clients and API tokens) is front-loaded. Slightly cramped grammar around 'with its name and last use,' 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 and no parameters, the description carries the return-shape burden and does so adequately by naming the fields returned and the 'current' flag. No pagination, ordering, or empty-result behavior is stated, but those are minor for a zero-arg enumeration tool.

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

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

The tool takes zero parameters, so the baseline is 4. The description still earns its keep by mentioning clientId in the context of revoke_agent, telling the agent what field from this listing is actionable elsewhere.

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 resource precisely: every agent client with access to the owner's account, explicitly scoped to OAuth clients and API tokens, with the returned fields named. An agent can distinguish this from generic list_* siblings like list_connections, though the description never names an alternative.

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

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

Usage is only implied — an agent infers it should call this to enumerate connected clients. The one explicit routing statement ('Pass a clientId to revoke_agent') points at a follow-up tool rather than explaining when to use this one versus siblings, and no exclusions are given.

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 cover the safety profile (readOnly, idempotent, non-destructive, not open-world). The description adds useful behavioral detail beyond that: it filters to unused, unexpired links for the current handle, orders newest first, and explicitly notes that the link URL itself is never returned.

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-loads the most important selection criteria and return shape. Each sentence carries useful information, including the non-obvious warning that the link itself is never returned and the follow-up action for revocation.

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

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

With no output schema, the description carries the burden of explaining return values and does so by listing the exposed fields (id, eventType, email, createdAt, expiresAt) and the exclusions. Combined with rich annotations, it gives the agent everything needed to select and interpret this zero-parameter list tool.

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

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

The tool takes zero parameters, so there is no parameter schema to explain. The mention of passing an id to revoke_booking_link refers to using an output id with another tool rather than a parameter of this tool, which is helpful context but does not change the zero-parameter baseline.

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 the exact resource (booking links) and scopes it tightly to links that can still book for the current handle, distinguishing it from the sibling list_bookings. It also enumerates the returned fields and ordering, so an agent knows precisely what the tool produces.

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 implied by the filtering criteria ('can still book') and by the pointer to revoke_booking_link for revocation, but there is no explicit when-to-use versus alternatives or when-not-to-use guidance. The agent can infer the purpose but must decide on its own when this tool is preferable to list_bookings or other listing tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. Beyond restating the upcoming parameter's meaning, the description adds no behavioral context — no note on ordering, result size, pagination, or whether the owner is derived from the authenticated caller.

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 no wasted words, and the scoping/default information comes first. The terseness borders on fragmentary but nothing is padded.

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 single-optional-parameter, read-only list tool with full annotation coverage and no output schema, this is close to sufficient. It still omits what the false case returns and any hint about result volume, which are the remaining questions an agent would 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%, so the description carries the burden and does: it states the default (true) and the effect (future bookings only). The gap is that it never says what upcoming=false yields (presumably all bookings including past ones), leaving the inverse case unstated.

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 fragment 'The owner's bookings' names the resource and its scope (the owner's), which is enough to distinguish it from siblings like list_booking_links or list_calendars. However, it is a noun phrase rather than a verb+resource statement, and it never explicitly says it lists/returns them, so the operation is inferred from the name and title.

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 explains what the single parameter does but gives no guidance on when to call this tool, when not to, or which sibling to prefer for alternate views. No prerequisites or auth context is stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real domain semantics beyond that: what 'holidays' means (events marked free, closes days only via rules.js daysOff) and the out-of-band dependency on Google Calendar for shared calendars. This is substantive behavioral context.

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?

Front-loaded with the primary scope, then the caveat about shared calendars last. It is dense but each clause carries information about returned fields. The nested parenthetical about holidays and rules.js is harder to parse than necessary, slightly hurting structure.

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

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

With no output schema, the description carries the burden of explaining return fields and does so comprehensively, plus a dependency caveat. Annotations cover the safety profile. The only gap is not clarifying its relationship to get_calendar_refs.

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?

Zero parameters, so there is nothing for the description to compensate for; baseline 4 applies. The schema is empty and the description correctly focuses on return semantics instead.

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 resource and scope ("Every calendar across all connections") and enumerates the fields returned (id, name, access role, rules.js participation, holiday status, stdlib ref). An agent knows exactly what set and shape of data this returns. It does not, however, distinguish itself from the close sibling get_calendar_refs, which likely overlaps.

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: it lists all calendars with no stated condition for choosing it over get_calendar_refs or list_connections. The one piece of guidance given — a shared calendar must be added in Google Calendar by its owner first — is a useful troubleshooting prerequisite rather than a when-to-use rule.

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 establish read-only, idempotent, non-destructive behavior, and the description goes further by disclosing the health state enum (ok/limited/expiring/revoked/blocked) and the rule that non-ok connections carry a reconnectUrl to be handed to the owner verbatim. It does not discuss auth or rate limits, but adds genuine semantic context beyond the 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?

Roughly two sentences of dense, information-rich prose with no filler. It front-loads the resource but leads with a fragment rather than a verb, slightly weakening scannability.

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

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

With no output schema, the description correctly carries the burden of explaining return values and does so by spelling out the health object fields and enum states plus last error. Coverage is strong for a zero-parameter lister; only actor/permission context is absent.

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 are zero parameters and the empty schema leaves nothing to document, so the baseline is 4. The description adds no parameter meaning because none exist; no gap is created.

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 resource — connected calendar accounts — and enumerates the returned fields (label, health, last error), so an agent knows exactly what it retrieves. It never names a sibling like get_calendar_refs or list_calendars to distinguish scope, so it stays at 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?

The description implies usage (inspect connection health, retrieve reconnectUrl when a connection is not ok) and even instructs to 'give it to the owner as returned,' which is a usage hint. It contains no explicit when-to-use-vs-alternative or exclusion guidance, leaving the agent to infer 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds two behavioral facts beyond the annotations: results are ordered newest-first, and the live version carries its rulesJs. It does not say how many versions are returned, whether historical versions also carry rulesJs, or anything about pagination.

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 no filler, and the most important fact (ordering) is front-loaded ahead of the edit-workflow hint. Nothing could be trimmed without losing 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?

With no output schema and no parameters, the description is the only source of return-value context, and it only partially covers it: ordering and the live version's rulesJs are mentioned, but the shape of a version entry (fields available on historical versions, count/pagination) is left unstated. Adequate for a simple zero-arg list tool, but not complete.

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

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

The tool takes zero parameters, so there is no parameter semantics to document and the baseline is 4. The description correctly does not waste space on nonexistent inputs.

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 the resource (config versions) and its ordering (newest first), which is enough to distinguish it from unrelated siblings like list_bookings or list_calendars. It is a noun phrase rather than an explicit verb (e.g., 'list/retrieve'), so it is clear but not maximally crisp.

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 workflow hint — 'start every edit from it' — which tells the agent to consult this before mutating config, but it never states when to use this tool versus any alternative, and no sibling is named. Usage is implied rather than spelled out.

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, so the safety profile is covered; the description adds real behavior beyond that — the previewId is valid 30 minutes and bound to exactly this source, and dependent tools refuse without it. It also discloses that a failed run returns the error instead of slots. Only the absence of any note on compute cost or live-event side effects keeps it from 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?

Purpose is front-loaded in the first clause, and the return shape, lifecycle, and workflow advice follow in a compact paragraph with no filler. It is dense and slightly run-on, which costs it the top score, but every sentence carries 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?

There is no output schema, so the description must carry return semantics — and it does: ok/error behavior, warnings, slotCount, byDay with a date/slot-time example, and diff against the live version. Combined with the previewId lifecycle and the workflow instruction, an agent has everything needed to call and interpret 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 all four parameters including the rules_js/version_id 'omit to preview a stored version' relationship and event_type slugs. The description restates the rules.js-or-stored-version choice but adds no format or syntax detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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 ('validate rules.js ... and run it against the owner's live events') and frames the outcome ('Show what the owner's page would offer'). No sibling tool does previewing, so it is trivially distinguishable from list_versions, explain, and get_skill.

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?

Gives explicit operational guidance ('Run after every change and show the owner a few days of slots') and states a gating condition: push_config, or activate_version on a draft, refuses without the previewId. It stops short of naming alternative tools or an explicit when-not-to-use case, so it is a strong 4 rather than a 5.

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