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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description still adds real behavioral context: required scopes (analytics:read, luca:read), data sensitivity (redacted), and the fact that idempotency is not required. That is meaningful disclosure beyond the annotation set.

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 and sentences are short. The trailing block of operation/scopes/idempotency lines reads as generated boilerplate but each line carries distinct information, so little 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?

For a two-parameter read tool with a full output schema and complete safety annotations, the description supplies the remaining pieces an agent needs: auth scope, sensitivity, and workspace override behavior. Only the lack of explicit sibling routing keeps it from being fully 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?

Schema description coverage is 100%, so the baseline is 3. The description adds one useful nuance (workspaceId/workspaceSlug override the environment-configured default workspace), which is slightly more than the schema's bare 'Optional Luca workspace id override' but not substantial.

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 (read the coach's cross-coach benchmark opt-in state) and clarifies the semantics of that state with a parenthetical definition. It implicitly separates itself from luca_analytics_benchmarks by scoping itself to consent rather than benchmark data, though it never names that sibling 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?

Provides a clear exclusion: the opt-in 'is changed from the app, not through this key surface,' telling the agent not to attempt a mutation here. It lacks a positive 'use when' statement or a named alternative tool, so the routing guidance is one-directional.

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 (readOnlyHint, idempotentHint, openWorldHint=false), and the description adds real context beyond them: required scopes (analytics:read, luca:read), 'data sensitivity: redacted', the fact that no idempotency key is required, and the expected pre-population state of the benchmark pipeline. That last point in particular prevents an agent from misreporting an empty result as an error or fabricating a comparison.

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 opening prose sentence is front-loaded with the core distinction and the comingSoon semantics before the metadata block, which is compact and scannable. Minor slack exists in the near-duplicate scope lines ('Required scopes: analytics:read' vs 'Required OAuth scope: luca:read') and the idempotency line, which largely restates idempotentHint.

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 an output schema present, return-value detail is correctly omitted, and the description supplies the pieces the schema cannot: required scopes, sensitivity level, workspace-override behavior, and the expected empty/comingSoon state. Complete enough to invoke correctly, though it stops short of naming adjacent tools an agent might confuse it with.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning the terse schema does not: it tells the agent these two parameters override 'the default workspace configured by environment', which explains why passing neither is valid. It does not explain precedence between workspaceId and workspaceSlug if both are supplied, which keeps it short of a 5.

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 ('cross-coach benchmark percentiles') and pins the scope hard with 'this coach's own... never another coach's data', reinforced by a concrete example ('top 15% for response speed among fitness coaches'). It is only slightly weaker than a 5 because it never names a sibling (e.g. luca_analytics_benchmark_consent) to route the agent away from related 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?

Usage is implied rather than stated: the agent can infer this is the tool for peer percentile comparisons, and the note that 'comingSoon: true with an empty metrics list is the honest, expected state' is useful invocation guidance. There is no explicit when-to-use/when-not, and no differentiation from sibling analytics tools such as luca_analytics_benchmark_consent or luca_analytics_funnel.

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 the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description adds meaningful context beyond them: required analytics:read and luca:read OAuth scopes, redacted data sensitivity, and the provenance of the metrics (post-call events and coach-recorded outcomes). The 'does not require idempotency' line is redundant with idempotentHint=true but not contradictory.

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 and the operational metadata is stacked compactly below. Slight redundancy between 'Required scopes: analytics:read' and 'Required OAuth scope: luca:read', plus the unneeded idempotency note, but overall it earns its space.

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 an output schema present, the description correctly avoids explaining return values, and it covers auth/scopes and data provenance for a read-only analytics call. The one material gap is the absence of any differentiation from the sibling luca_analytics_call_intelligence_calls, which an agent selecting among analytics tools would need.

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%: workspaceId and workspaceSlug already carry descriptions, while query.start/end do not. The description adds the override semantics for the workspace params and implies the start/end period via 'for a period', which partially compensates for the undocumented date-range params, but adds no format or default-window detail. Baseline 3 fits.

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 (post-call intelligence) and enumerates the metrics returned: show rate, close rate, rating distribution, call-to-close lag, repeat-call cohort, day-of-week/sequence show rates, and surprise patterns. However, it never distinguishes itself from the near-identical sibling luca_analytics_call_intelligence_calls, so an agent cannot disambiguate the two from the description alone.

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 guidance is a parameter tip (use workspaceId/workspaceSlug to override the environment default), which is invocation detail rather than usage context. There is no when-to-use, when-not-to-use, or alternative selection guidance against the many other analytics tools in the sibling list, especially luca_analytics_call_intelligence_calls.

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/openWorld=false, so the safety profile is covered; the description goes further by disclosing required scopes (analytics:read, luca:read), data sensitivity (full_content), the completed-with-summary filter, and newest-first ordering. This is useful behavioral context beyond the structured fields.

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 resource and scope in the first sentence, followed by compact metadata lines. Efficient overall, though the boilerplate operation/idempotency lines are somewhat mechanical rather than decision-relevant.

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?

An output schema exists, so return values need not be spelled out, and the description covers scopes, sensitivity, ordering, and workspace override. The only real gap is the undocumented limit semantics, otherwise it is complete enough for a read-only listing tool.

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

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

Schema coverage is 67%, with workspaceId/workspaceSlug already documented in the schema, and the description usefully explains the override intent ('override the default workspace configured by environment'). However the limit parameter (1–50, no default stated) is left undescribed in both schema and text, so it does not fully compensate.

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 (List) and resource (calls behind call intelligence) and further narrows scope to 'most recent completed calls with a generated summary, newest first,' even naming the returned fields. That is clear enough for an agent to know what it retrieves, though it never contrasts itself with the related luca_analytics_call_intelligence or the call_events_* siblings.

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

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

The description implies when to use it (to surface recent, summarized, completed calls) and gives workspace-override guidance, but offers no explicit when-not or alternatives despite a very crowded sibling set of call/analytics tools. Usage is inferable but not routed.

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 genuine value beyond that: how attribution is derived (Instagram comment or Story reply with a real media id, or manual tagging), the empty-list semantics, data sensitivity (redacted), and required scopes. These are behavioral facts an agent cannot get from 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?

The core purpose is front-loaded in the first sentence, followed by attribution mechanics, then a compact metadata block (operation, scopes, idempotency, workspace). Mostly efficient, though the 'Does not require idempotency' line is slightly redundant against the idempotentHint=true annotation and mildly confusing.

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?

An output schema exists, so return values need not be spelled out. Given that, the description covers the essentials: what is computed, how attribution works, the meaning of an empty result, scopes, and workspace targeting. Only the period enum values remain unexplained.

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 67%, so the baseline is 3. The description clarifies the workspaceId/workspaceSlug purpose as an override of the environment-configured default, which adds meaning. The 'period' parameter and its enum values carry no descriptive detail in either the schema or the description, leaving a 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?

States a specific operation ('Per-content rollup') with the exact metrics returned (leads touched, qualified, booked, revenue) and the scope ('attributed touches for a period'). This is far more concrete than a tautology. It does not, however, differentiate itself from the close sibling luca_analytics_content_performance, which an agent would need to disambiguate against.

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 by the read-analytics framing. The description does add a useful interpretation rule ('an honest empty list means no content is attributed yet, not zero performance') and workspace override guidance, but it never states when to choose this over alternatives like luca_analytics_content_performance or luca_analytics_topic_performance.

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, openWorldHint and destructiveHint, so the safety profile is covered. The description adds genuinely non-derivable behavior: insight fields stay null until the account grants Instagram insights access 'read that as not connected yet, not zero engagement' — a critical interpretation hint that prevents a false zero-engagement reading. It also discloses required scopes and data sensitivity ('redacted').

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 lead sentence is front-loaded and information-dense, but it crams a long metric enumeration into one run-on. The operational block contains partly wasteful lines: 'Does not require idempotency' merely restates the idempotentHint annotation, and the endpoint path adds little for an agent choosing a 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?

An output schema exists, so return shapes need not be described, and there are zero required parameters, lowering the burden. Between the metric list, the null-insights caveat, the workspace override note and the scope declaration, an agent has enough to call it correctly; only the missing differentiation from the related attribution/topic tools leaves a gap.

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

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

Schema description coverage is 67% and all three parameters are named in the schema, including the workspace override semantics the description repeats verbatim. The description says the rollup happens 'over a period' but does not add meaning to the period enum (this_week, last_month, etc.) beyond what the schema already lists, so 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 ('per-post rollup ... for each Instagram post, reel, story, or carousel over a period') and enumerates the metrics returned, which is far more than a restated name. However, it lists 'attributed leads/bookings/revenue' — material that overlaps heavily with the sibling luca_analytics_content_attribution — without any sentence distinguishing 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 by the metric inventory and the period parameter, but there is no explicit when-to-use statement nor any when-not guidance or named alternative among the many analytics siblings (content_attribution, topic_performance, benchmarks). The only actionable guidance ('Use workspaceId or workspaceSlug to override...') is parameter mechanics rather than tool selection.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the safety profile is covered; the description nonetheless adds real context beyond them: required scopes (analytics:read, luca:read), 'data sensitivity: redacted', the underlying GET endpoint, and that no idempotency key is needed. The idempotency line mildly duplicates idempotentHint=true, keeping this short of 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 and the enumerated counters lead, followed by compact operational metadata lines (endpoint, scopes, sensitivity, idempotency, workspace override). Every line carries information, though the blocky metadata formatting is slightly heavier than prose would 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 annotations, a full output schema, and 100% param coverage, the description only needs to add auth/behavior context, which it does (scopes, redaction, default workspace). It is essentially complete for calling the tool correctly; the main omission is routing guidance against sibling CRM-health/sync tools.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining the semantic role of both params — they override the default workspace derived from the environment, a fact absent from the schema's terse 'optional override' 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?

States a specific verb and resource (aggregate CRM-sync health) and enumerates the exact counters returned (synced, pending, local-only, failed, permanently-failed), which lets an agent predict the payload. It scopes the tool to the coach's post-call summaries, though it never explicitly contrasts itself with near-neighbors like luca_integrations_crm_connections_health or luca_integrations_crm_sync_runs_list.

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 line about all-zeros being the expected state for coaches with no synced summaries is useful interpretive guidance, and the workspaceId/workspaceSlug override sentence establishes a default-workspace behavior. However, there is no explicit when-to-use vs. an alternative (e.g., sync_runs_list for run-level detail), so usage is only implied.

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 behavior. The description adds the aggregation trait (seven reads composed in one call) and notes the forecast is point-in-time, which is real context beyond the annotations, though it stops short of describing rate limits or auth requirements.

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 core purpose, then differentiation, then a worked example. The seven-item enumeration is dense but each entry earns its place by defining the tool's scope; the text is slightly heavy but never wasteful.

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 an output schema present, return values need no explanation, and the annotations carry the safety profile. The description covers scope, aggregation behavior, differentiation, and an example, leaving nothing an agent needs in order 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 the schema already documents period, question, workspaceId, and workspaceSlug. The description's example shows period and question usage but adds no syntax or semantics the schema lacks, making the baseline 3 appropriate.

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

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

States a specific verb and outcome ('Answer a specific business question by composing all seven analytics reads in one call') and then enumerates exactly which reads are included. It explicitly distinguishes itself from luca_analytics_magic_monday, so an agent can separate the two 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?

Names the alternative (luca_analytics_magic_monday) and the condition that selects this tool instead: when the coach asks a specific question needing cross-referencing several numbers. The concrete example call reinforces when and how to invoke 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 cover read-only, idempotent, non-destructive behavior. The description adds useful operational detail beyond them: required analytics and OAuth scopes, redacted data sensitivity, and the fact that no idempotency key is required. It does not mention rate limits or freshness, so it is not 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 description is front-loaded with the core forecast concept, followed by concise operational metadata. Every line is useful and there is no redundant 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?

With an output schema present and rich annotations, the description sufficiently covers what the tool returns, required scopes, sensitivity, and workspace override behavior. An agent has enough information to invoke it correctly.

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

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

Schema coverage is 100%, so the schema already documents both optional workspace parameters. The description adds meaning by explaining that workspaceId or workspaceSlug override the environment default workspace, which goes beyond the per-parameter schema text.

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

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

The description clearly states a specific resource and output: a point-in-time pipeline revenue forecast with on-track, optimistic, and conservative scenarios. It does not explicitly differentiate this tool from sibling analytics tools like luca_analytics_revenue, so it falls short of the sibling-differentiation bar for 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?

The description provides invocation prerequisites such as required scopes and how to override the default workspace, which implies usage context. However, it does not explicitly state when to choose this forecast tool versus alternatives such as luca_analytics_revenue.

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 read-only/idempotent/destructive profile, and the description supplements it with genuinely useful context: required scopes (analytics:read, luca:read), data sensitivity (redacted), the underlying GET operation, and default-workspace override behavior. 'Does not require idempotency' is slightly redundant against idempotentHint=true but not contradictory.

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 and return shape are front-loaded in the first sentence, followed by a compact metadata block. It is well organized with no wasted prose, though the trailing metadata lines are status boilerplate rather than decision-relevant.

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?

An output schema exists, so return values need not be detailed in prose, and the annotations carry the safety profile. The description still names the return payload and documents auth/scoping, leaving little an agent needs to call it correctly missing.

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

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

Schema coverage is 67% – the two workspace parameters carry descriptions while the nested period/channel properties show only enums with no prose. The description names 'period and channel filters', bridging part of that gap, but adds no format or default meaning beyond 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?

First sentence states a specific resource (pipeline funnel stage counts) plus the filters and returns (counts, conversion rates, period-over-period deltas). Clear and actionable, but it does not explicitly differentiate from sibling analytics tools such as luca_analytics_rollup or luca_analytics_deep_dive that could plausibly overlap.

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 the many other analytics tools. The only usage-adjacent line is the workspace override note, which concerns parameters, not tool selection. An agent is left to infer fit from the name alone.

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 read-only, idempotent, non-destructive, closed-world behavior. The description goes further by disclosing required scopes (analytics:read, luca:read), data sensitivity (full_content), and the absence of an idempotency-key requirement, which an agent needs before calling. It does not describe pagination or rate limits, but for an aggregate read that is minor.

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-loads the substance (what is measured, and that it is an aggregate) before the routing sentence and the operational metadata block. The operation/scope/idempotency lines are somewhat boilerplate but each carries actionable info; nothing is redundant with the annotations.

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 an output schema present, return values need not be described, and the description instead covers scope, sensitivity, workspace resolution, and report shape. Remaining gaps are the optionality/defaults of period and channel, which the schema does not fill in either.

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% and the nested query object's period/channel enum properties carry no descriptions. The description mentions period filtering only in passing ('during a period') and never explains channel, so it does not compensate for the gap. It does add real meaning for the workspace override ('override the default workspace configured by environment'), which the schema alone does not 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 resource ('Summarize leads who stopped replying') and enumerates the exact outputs: count, follow-up recovery rate, estimated lost revenue, and stall reasons. The explicit contrast 'This is an aggregate report, not a list of individual leads' separates it from luca_leads_list and other list-shaped siblings.

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

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

Gives clear context ('during a period') and an explicit negative: it is an aggregate report, not a per-lead list, which steers agents away from list tools. It does not name a concrete alternative or state when to prefer this over neighboring analytics tools such as luca_analytics_loss_reasons or the action-oriented luca_rescue_silent_leads, so guidance stops short of the top mark.

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), but the description adds real behavioral context: the empty-list-is-expected semantics to prevent fabricated alerts, the data source/refresh cadence, required scopes, and 'data sensitivity: redacted'. It does not describe pagination/truncation behavior, which is a minor gap given the maxPages parameter.

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 prose portion is front-loaded and efficient, leading with what the feed is and following with the filter and empty-state caveat. The template metadata lines (operation, scopes, idempotency note) add bulk but each carries operational information; the 'Does not require idempotency' line sits awkwardly next to idempotentHint=true.

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 read-only list tool with an output schema, the description covers what the agent most needs: scope requirements, workspace override, ordering, and the honest-empty-state warning. It is essentially complete, with pagination behavior left to the schema.

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

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

Schema description coverage is 75%, so several params (maxPages, workspaceId, workspaceSlug) are documented in-schema while nested query fields (limit, cursor, status) are not. The description explains the status filter's meaning and the workspace override, adding some value, but says nothing about limit/cursor pagination semantics, so the baseline 3 is right.

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 concrete resource (the coach's proactive-insights feed) and lists its content categories (metric drops/spikes, opportunities, risks, milestones) plus its source and ordering (daily cron, newest first). It clearly distinguishes itself from the mutation siblings (mark_read, dismiss, mark_actioned), though it never explicitly names the closest read sibling, luca_insights_unread_count.

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 states the optional status filter with an example ('unread') and how to override the default workspace, which is useful invocation context. However, it gives no explicit when-to-use/when-not guidance relative to alternatives such as luca_insights_unread_count or the triage/recommendations tools, leaving selection 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 already cover readOnly/idempotent/non-destructive/openWorld=false, but the description adds material behavioral context beyond them: the model admits insufficient data by returning a null score and low confidence rather than fabricating a value, notes data sensitivity 'redacted', and lists required scopes. This exceeds what the structured fields convey.

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 core value proposition is front-loaded in the first sentence, and the operational block (endpoint, scopes, idempotency, workspace override) is compact. The 'Does not require idempotency' line is somewhat redundant with idempotentHint=true, a minor waste.

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

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

An output schema exists, so return structure needn't be explained, and the description covers scopes, workspace overriding, and the null/low-confidence edge case. It is essentially complete for a single-lead read; only explicit alternative-tool guidance is missing.

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

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

Schema coverage is 67%; workspaceId and workspaceSlug are already documented in the schema, and the description only restates their override role. leadId is required but has no textual meaning in either place, so the description does not fully compensate for the gap. Baseline 3 is appropriate.

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

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

States a specific verb+resource: a predictive booking-likelihood score (0-100) for one lead, derived from a trained bucket-rate model, plus its return components (confidence tier, top features). This is highly distinctive; no sibling analytics or leads tool returns a per-lead model score, so an agent can identify it immediately.

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 usage context for the workspace override ('Use workspaceId or workspaceSlug to override the default workspace configured by environment'), which is helpful. However, it never states when to use this tool versus adjacent options such as luca_leads_explain or the other analytics tools, leaving that 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 already cover readOnly/idempotent/destructive/openWorld, so the bar is lower; the description still adds required scopes (analytics:read, luca:read), data sensitivity redacted, the underlying endpoint, and the honest-empty-state behavior. It adds real operational 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?

Purpose and payload are front-loaded, then operational facts (endpoint, scopes, idempotency, workspace override) follow in compact lines. It is a bit list-heavy but every line carries information an agent can use.

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 an output schema present, return-value documentation is not strictly required, yet the description still summarizes the shape and the empty-state semantics. Auth, workspace targeting, and scope requirements are covered, making it complete enough to invoke correctly.

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

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

Schema coverage is 67%: workspaceId/workspaceSlug are documented in the schema, and the description mirrors that they override the environment default workspace. The start/end period parameters are only obliquely referenced via 'for a period' and left entirely to the schema, so the description adds little beyond structured fields.

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+resource ('read-only rollup of agent-improvement signals mined from post-call feedback') and enumerates the payload (counts, per-type breakdown, example notes). It is clear about scope, but it never distinguishes itself from near-neighbors like luca_learning_panel, luca_learning_framework_performance, or luca_analytics_insights.

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 useful context that an empty rollup is the expected state until feedback is submitted, and notes workspace override, but it gives no explicit when-to-use or when-not-to-use guidance relative to the many sibling analytics/learning tools. Usage is implied rather than directed.

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 goes beyond them by disclosing required scopes (analytics:read, luca:read), the redacted data sensitivity level, that idempotency is not required, and the data's provenance (derived from per-lead loss analysis generated when a lead goes silent/lost). Only rate limits or refresh cadence are absent.

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 and category list are front-loaded in the opening sentence, followed by compact metadata lines (operation, scopes, idempotency, workspace override). Some density in the first sentence but no wasted 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?

With a rich output schema, annotations, and covered parameters, the description supplies the remaining essentials: auth scopes, sensitivity, and how the data is produced. Only the period semantics and sibling disambiguation are left implicit.

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%; both workspaceId and workspaceSlug already have their own descriptions, and the description merely restates the override behavior. The period parameter and its five enum values are not explained in the description, so it adds little beyond 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 names a specific resource (category breakdown of 'why you lost' analyses) and enumerates the exact categories returned plus the metric (count and estimated lost revenue). It is clearly not a generic analytics tool, though it never explicitly contrasts itself with close siblings like luca_analytics_objections or luca_analytics_ghosted_leads.

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 is a read analytics call for a given period, and the last line gives a concrete hint for overriding the default workspace. There is no statement of when to prefer this over the sibling loss/objection analytics tools, nor any exclusions.

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 useful context beyond them — the aggregation of five reads and the 'current week' time scope — but says nothing about cost, latency, or rate behavior of the composite 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?

Front-loads the core action and scope in the first sentence, enumerates contents compactly, then gives the empty-args example. No filler; every clause 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?

With an output schema present, return values need not be explained, and the description makes clear the scope is the current week and the call is optional-argument. Adequate for a zero-required-param read tool; only minor missing detail such as how workspace context is otherwise resolved.

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 both optional workspace override params are documented in the schema. The description's '{} for the weekly report' reinforces that no arguments are required, but adds no syntax or semantics beyond what the schema already provides. 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 ('Return the current week's business report'), enumerates the exact contents (funnel, revenue/ROI, speed impact, forecast, call intelligence), and explicitly says it composes five analytics reads. An agent can distinguish it from luca_analytics_funnel/revenue/forecast etc. purely from the description.

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 phrase 'Composes five analytics reads into a single call' plus the '{} for the weekly report' example tells the agent this is the aggregate entry point versus the individual analytics siblings. It stops short of an explicit 'use this instead of X when Y', so it is clear context without full routing rules.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new operational context: required scopes (analytics:read, luca:read), full_content data sensitivity, limit-bounded results with a hasMore truncation flag, and the empty-state contract. Only return-format/pagination mechanics are left implicit.

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-loads the semantically valuable row-shape sentence, then groups the operational metadata (operation, scopes, idempotency, workspace override) in a compact block. Slightly boilerplate-heavy ('Luca operation: GET /api/...', 'Does not require idempotency') but every line is short and no sentence 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 an output schema present, the description need not restate return values, yet it still covers access prerequisites (both scope layers), sensitivity class, pagination behavior, the default-workspace override path, and the empty-state contract. For a nested-schema, read-only analytics tool this leaves nothing material an agent needs before 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 description coverage is 50% (only workspaceId/workspaceSlug are documented). The description adds that limit bounds results, that hasMore signals truncation, and that workspace override is possible – but it says nothing about the period or channel sub-parameters or the objection type enum values, leaving half the surface to 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?

States a specific verb+resource ('per-conversation drilldown for one objection bucket') and enumerates the row shape (lead name, verbatim objection quote, draft-edited flag, latest call outcome), which makes it distinguishable from the aggregate sibling luca_analytics_objections without opening the schema. It never names that sibling explicitly, so the contrast is implied rather than 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?

Implies the use case (getting per-conversation detail behind one objection bucket) and notes the empty-list case is expected plus that workspaceId/workspaceSlug override the environment default. It gives no explicit when-to-use-this-vs-luca_analytics_objections routing or prerequisites beyond scope declarations.

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 readOnly/idempotent/non-destructive, but the description adds real value beyond that: required scopes (analytics:read, luca:read), data sensitivity (full_content), workspace override behavior, and the notable empty-state expectation ('never fabricated'). It stops short of rate limits or pagination behavior.

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 purpose is front-loaded in the first sentence with the key output fields, followed by a compact metadata block (operation, scopes, idempotency, workspace override). Slightly dense but every line carries actionable 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 read-only analytics rollup with an output schema present, the definition covers scope, auth requirements, sensitivity, and the semantics of an empty result. Nothing critical to invoking it correctly appears to be missing.

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

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

Schema description coverage is 67%, and the description compensates by explaining that period governs the rollup window, that channel is a filter, and that workspaceId/workspaceSlug override the environment-configured default. It does not add format or default-value detail beyond the schema's enums.

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 (objection-bucket rollup over review-queue qualifier signals) and enumerates the exact buckets and output metrics, so the agent knows precisely what it returns. It does not explicitly name or contrast the closely-named sibling luca_analytics_objection_drilldown, so sibling differentiation is only implicit through 'rollup'.

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 filter condition ('Filter by channel') and workspace override guidance, which implies usage context for an analytics read. However there is no explicit when-to-use/when-not guidance and no routing toward alternatives such as the drilldown variant.

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 goes beyond that with the authorization surface (analytics:read, luca:read, full_content sensitivity), the weekly generation cadence, dedup semantics, and the empty-list expectation. It stops short of describing pagination or response shape, but the output schema exists for that.

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 what-it-is sentence, followed by clearly delineated operational metadata on separate lines. The empty-state sentence is the one addition that carries genuine interpretive value. Slightly more surface area than needed, but nothing is 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?

With an output schema present, return values need not be described, and the description correctly focuses on auth scopes, workspace override, cadence and empty-state semantics. The remaining gap is routing: with dozens of analytics siblings available, the description never tells the agent which one to reach for instead.

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 67%, so the baseline is 3. The description usefully adds the default-workspace behavior and the override intent for workspaceId/workspaceSlug — a real semantic gain over the schema's terse "optional override" wording. It says nothing about weekStart or includeDismissed, which the schema also leaves undocumented, so a portion of the parameters remain opaque.

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 opening sentence gives a specific resource and scope: the coach's active prescriptive recommendations for a given week, deduped by title, generated from detected insights. An agent knows exactly what this returns. It does not explicitly distinguish itself from close siblings like luca_analytics_insights or luca_analytics_learning_insights, so a 5 is not warranted.

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 interpretive guidance — an empty list is the expected, honest state and never a fabricated action — which is useful for an agent deciding whether to act. However, it never states when to prefer this tool over the many adjacent analytics siblings (insights, trends, learning_insights, objections). Usage is implied by the weekly-recommendation framing rather than addressed explicitly.

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 safety (readOnlyHint, idempotentHint, destructiveHint, openWorldHint), so the bar is lower; the description still adds auth requirements (analytics:read, luca:read), the redacted data sensitivity, and the workspace-override fallback behavior. It does not describe rate limits or pagination, but for a read-only endpoint that is a minor gap.

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 and return shape are front-loaded in the first two sentences, followed by an operation/scope metadata block. No sentence is wasted, though the metadata reads as boilerplate stacked after the useful content.

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 an output schema present the description need not explain return values, and annotations cover safety, so purpose + auth scopes + workspace behavior covers most needs. The one missing element is differentiation from the many sibling analytics endpoints.

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 67%, and the description only lightly touches parameters: it says results are 'for a period' and explains workspaceId/workspaceSlug as overrides. The nested query.period and query.channel enums (five period values, four channels) are left entirely to the schema. Baseline 3 is appropriate given the medium coverage and modest descriptive contribution.

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+resource: 'Revenue attribution and plan ROI for a period' and enumerates outputs (total revenue, ROI, per-channel breakdown). It's clear what the tool does, but it does not distinguish this from sibling analytics tools like luca_analytics_rollup, luca_analytics_forecast, or luca_analytics_content_attribution.

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 / when-not-to-use guidance and no named alternatives despite a dense set of analytics siblings. The only operative sentence concerns workspace override parameters, which is parameter behavior rather than usage selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely non-obvious behavior: a partial-failure mode where one half still returns and failedSections names the missing section, which is exactly the kind of operational context annotations cannot express.

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

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

Three sentences, front-loaded with the purpose, then the failure behavior, then a concrete invocation example. Every sentence carries information, with only mild overlap against the schema's own default-limit note.

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 an output schema present, return-value documentation is unnecessary, and the description still flags the failedSections field for degraded responses. Scope, default behavior, and invocation are all covered; the only real gap is routing against sibling analytics tools.

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 workspaceId, campaignLimit, and workspaceSlug, establishing a baseline of 3. The description only reinforces the default limit and gives a concrete example ({ campaignLimit: 3 }), adding marginal value over 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?

States a specific verb (roll up) and the two resources combined (per-campaign analytics for up to 5 recent campaigns plus recent broadcasts), so an agent knows the scope is a combined rollup. However, it never names or contrasts with the close sibling luca_campaigns_analytics, which also returns campaign performance, so the differentiation is left to 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?

Usage is implied by the 'roll up' framing and the example invocation, giving a sense of what the tool is for. But there is no explicit when-to-use/when-not guidance and no routing to alternatives such as luca_campaigns_analytics or luca_broadcasts_list, despite many overlapping analytics 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds valuable context beyond annotations: the required analytics:read / luca:read OAuth scopes, redacted data sensitivity, and the fact that no idempotency key is needed.

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 purpose and returns are front-loaded in the first sentence, followed by compact operational metadata. The 'Does not require idempotency' line is marginally redundant given idempotentHint=true, but overall there is little waste.

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

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

For a read-only analytics tool with an output schema, the return values needn't be explained (though they are), and the description supplies scopes, sensitivity, and workspace override. The main gap is the unaddressed 'channel' filter and period enum values, but nothing critical 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?

Schema coverage is 67% (mid-range). The description echoes the period dimension ('for a period') and explains the workspaceId/workspaceSlug override purpose, but the 'channel' filter is never mentioned in the description, so a parameter visible in the schema is not contextualized. Adds modest value over 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 names a specific analysis ('Fast-vs-slow first-reply booking-rate impact for a period') with a clear verb-like action and resource, and enumerates the concrete outputs (fast/slow conversion rates, lost-opportunity estimate, peak reply window). It is clearly distinct from funnel/revenue/forecast siblings by its narrow focus, though it never names an alternative to route the agent 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: 'for a period' plus the note to use workspaceId/workspaceSlug to override the environment default. There is no explicit when-to-use versus other analytics tools (e.g. ghosted_leads, benchmarks) and no when-not 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 cover readOnly, non-destructive, idempotent, closed-world, but the description adds real context: required scopes (analytics:read, luca:read), redacted data sensitivity, and the important semantics that an empty items list is expected until topics are extracted rather than a signal of zero performance. The idempotency note is about idempotency keys rather than operation semantics and is slightly at odds with idempotentHint=true wording, but it is not a true contradiction.

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

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

Front-loads the rollup and its metrics, then layers defaults, state semantics, and auth in short sentences. Slightly boilerplate-heavy (operation path, idempotency line) but each line 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?

An output schema exists so return shape need not be explained, and the description still covers scope, sensitivity, default week behavior, workspace override, and the empty-result state. Complete enough for a read-only aggregate tool, with only sibling differentiation left implicit.

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 only 67%, and the undocumented parameter is weekStart; the description compensates by explaining its default-to-most-recent-week behavior. The workspace override parameters are documented in the schema, so the remaining description text adds marginal value there.

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?

Names a specific verb (weekly rollup) and resource (normalized content topic) and enumerates the returned metrics (post count, engagement rate, leads/bookings/revenue per theme). It does not explicitly distinguish itself from close siblings like luca_analytics_content_performance or luca_analytics_content_attribution, which an agent could easily confuse with a topic-level rollup.

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 useful operating context (weekStart defaults to the most recently computed week; workspaceId/workspaceSlug override the configured default workspace) but never says when to prefer this tool over the sibling content/attribution analytics tools. Usage is implied rather than stated.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world). The description adds genuinely useful behavioral context beyond them: an empty series is the 'honest, expected state' and points are 'never fabricated.' It also surfaces required scopes and data sensitivity (redacted).

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-loads purpose in the first sentence, then the empty-state caveat, then operational metadata. Every sentence carries some value, though the metadata block (operation, scopes, idempotency) is boilerplate-heavy and slightly inflates length.

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?

An output schema exists, so return shape need not be explained. The description covers the workspace override, the empty-state expectation, scopes, and data sensitivity — enough for an agent to call it correctly. The underexplained 'weeks' parameter is the only modest gap.

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

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

Schema coverage is 67% (weeks is undocumented in schema, workspaceId/workspaceSlug are documented), placing the baseline at 3. The description adds meaning for the workspace params by explaining they override the environment-configured default, but gives no semantic guidance on the 'weeks' window itself.

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: weekly metrics (leads, qualified, booked, revenue, rates) delivered as a week-over-week trend series. The 'for charting direction of travel' framing distinguishes it as a time-series read, separable from point-in-time siblings like analytics_revenue or analytics_funnel. It stops short of naming those siblings 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?

Implies usage via 'for charting direction of travel' but never states when to choose this over the many other luca_analytics_* siblings (funnel, forecast, rollup, deep_dive). No when-not or alternative routing is given, so usage is inferred rather than guided.

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 lower. The description still adds genuine behavior-relevant context beyond them: required scopes ('analytics:read', 'luca:read'), the data sensitivity level ('redacted'), and the note that no idempotency is required — all useful to an agent planning 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?

The human-readable purpose is front-loaded, followed by compact metadata lines (operation, scopes, idempotency, workspace override). Slight redundancy exists — 'Does not require idempotency' echoes the idempotentHint annotation — but overall it is tight and well-structured.

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?

An output schema exists, so return values need no prose explanation, and annotations carry the safety profile. Combined with the scope/sensitivity/workspace details, the description gives an agent enough to invoke it correctly; only the channel-filter semantics are left unaddressed.

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 67% (workspaceId/workspaceSlug are documented), but the nested period and channel enums have no descriptions. The prose repeats the workspace-override hint and mentions 'for a period', adding only marginal meaning beyond the schema and leaving the channel filter unexplained.

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 names a specific set of metrics ('draft approval, edit, and rejection rates plus the auto-send gate flag') and a scope ('for a period'), so the agent knows exactly what data this produces. It does not, however, explicitly differentiate itself from the many other analytics siblings (e.g. lead_score, funnel), which is the only reason it falls short of 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 adds operational guidance — 'Use workspaceId or workspaceSlug to override the default workspace configured by environment' — which is actionable. But it never states when to reach for this tool versus the other analytics endpoints, and there are no exclusions or prerequisites beyond the scope note, so usage remains implied rather than explicit.

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 flag destructiveHint and openWorldHint, but the description adds critical context beyond them: the message goes to a REAL person, human review is mandatory, and confirm: true is a hard gate. This is exactly the kind of real-world impact and workflow constraint an agent needs before invoking a destructive send.

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-loads the action and the safety warning, then states the confirm requirement and an example. No filler. The example is short and reinforces the calling pattern; minor room to trim without losing meaning.

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?

An output schema exists, so return values need not be described. All six parameters are documented in the schema, and the description covers purpose, safety, and the confirm gate. It could note retry/idempotency behavior, but overall it is sufficient to call the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description restates confirm: true and that finalBody replaces the draft text, plus gives a usage example, but it adds little meaning beyond what the parameter descriptions already supply.

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: 'Approve a pending review-queue draft and dispatch it through the lead's channel.' The action is unambiguous. However, it does not differentiate itself from the sibling luca_review_queue_approve, leaving the agent to infer how approve-and-send differs from plain approve.

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 a clear precondition: only call after a human has reviewed and intends to send, and requires confirm: true. This is a strong when-to-use gate, but no alternative tool (e.g. luca_review_queue_approve or luca_conversations_send) is named for cases where the draft should not be sent.

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?

Goes well beyond the annotations: discloses the pre-flight availability check, the fallback of returning open slots when the requested one is taken, the idempotencyKey exception that skips the check, and the downstream effects ('moves the lead to booked and notifies the coach's webhook subscribers'). That is exactly the side-effect detail destructiveHint=true and openWorldHint=true only gesture at.

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 most decision-critical constraint (no calendar event, no invite), then availability semantics, then confirm gating, then a concrete example. Dense but every clause carries operational weight; the example at the end is the only mildly expendable part.

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 8 parameters and a real output schema, the description covers side effects, preconditions, failure behavior, retry semantics and confirmation. There is no gap an agent would need to guess at.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: why provider matters for the availability read, that bookingTypeId must be an active google_calendar type, and how idempotencyKey changes retry behavior. It stops short of restating leadId/slotAt formats, which is fine because the schema covers them.

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?

Names a specific verb and resource ('Record a booked call for a lead in Luca') and immediately draws the boundary against what it is not: it does not create a calendar event or send an invite. An agent can distinguish it from bookkeeping siblings like luca_bookings_create without opening the 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?

Explicitly states the precondition path ('book the call with the provider too, or have the lead book through the coach's booking link') and the confirm-gating rule ('pass confirm: true only after the coach approves this exact slot'). What is missing is any routing against the near-siblings luca_bookings_create, luca_bookings_availability and luca_reschedule_call, which an agent could easily confuse this with.

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/openWorld/idempotent/non-destructive, so the bar is lower. The description still adds real value by disclosing required scopes (bookings:read, luca:read), data sensitivity (redacted), and the workspace override mechanism. The 'does not require idempotency' line is slightly redundant against idempotentHint=true but describes idempotency keys, not effect semantics, so it is not a genuine contradiction.

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

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

The intent sentence is front-loaded and the metadata lines (operation, scopes, workspace override) are compact and scannable. No filler sentences, though the 'Does not require idempotency' line is marginally redundant with the annotations.

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 an output schema present, return values need not be described, and the annotations already cover the safety profile. The description completes the picture with auth scopes and workspace-override guidance, leaving only the sibling-differentiation gap.

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

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

Schema description coverage is 67%, so the schema carries most parameter documentation. The description only clarifies the workspaceId/workspaceSlug override behavior and says nothing about the nested query filters (start, end, leadId, provider, timezone, calendarId, eventTypeId), leaving a gap the schema alone must fill.

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 ('List open slots the coach can actually be booked into') and even the intent behind it. However, it does not distinguish itself from sibling tools like luca_bookings_managed_availability or luca_bookings_types_schedule, which an agent could plausibly confuse with this one.

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 this before booking' gives one implied when-to-use condition, which is helpful context. But it names no alternatives and no exclusions, so an agent cannot tell from the description alone when to prefer this over luca_bookings_managed_availability.

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 core safety profile is covered. The description adds valuable behavioral context beyond annotations: API operation, required scopes, OAuth scope, and data sensitivity 'full_content', which tells the agent this returns sensitive personal data. It does not describe the return shape, but an output schema exists.

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 key purpose sentence and then provides structured technical metadata. It is appropriately sized for a simple read tool, though some operational notes (such as 'Does not require idempotency') are less essential given annotations and could be trimmed.

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 read-only endpoint with full annotations, an output schema, and three simple parameters, the description covers purpose, auth scopes, data sensitivity, and workspace override behavior. No critical information needed to invoke the tool correctly is missing.

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

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

Schema description coverage is 67%, with the workspaceId and workspaceSlug parameters already described. The description adds meaningful context by explaining that these parameters override the default environment-configured workspace. The required 'id' parameter is not described in the description, but its role is clear from the endpoint path and schema format.

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 ('Read the pre-call brief') and elaborates on the brief's contents, making the tool's purpose clear. It does not explicitly differentiate itself from sibling tools such as luca_bookings_get, which likely returns broader booking details.

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 purpose statement, but there is no explicit guidance on when to use this tool versus alternatives like luca_bookings_get or when a pre-call brief is available. The required scopes and workspace override notes add operational context but not selection 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 readOnlyHint/idempotentHint/non-destructive, so the safety profile is covered; the description adds genuinely new context beyond that, namely required scopes (bookings:read, luca:read) and the 'data sensitivity: redacted' handling. The 'Does not require idempotency' line simply restates 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?

Purpose is front-loaded in the first line, and the remaining metadata (endpoint, scopes) is scannable. One line, 'Does not require idempotency,' is redundant with idempotentHint=true and could be dropped, but the overall size is appropriate.

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 an output schema present, return values need not be explained, and the annotations cover the safety profile; the description fills in scope/auth requirements and default-workspace behavior. Only the absence of sibling-routing guidance keeps it from a 5.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: workspaceId/workspaceSlug are overrides of an environment-configured default workspace, which clarifies the default behavior an agent would otherwise have to guess.

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 (List), a specific resource (calendars Luca reads for conflicts), and adds a distinguishing detail: which calendar it writes new events to. An agent can place it against siblings like luca_bookings_calendars_select/remove 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?

Usage is implied (a read-only listing of connected calendars) and it does note when to use the workspace override, but it never states when to prefer this over the related calendars_select/calendars_remove siblings or what prerequisites exist. Guidance is present but shallow.

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 readOnlyHint=false, but the description adds genuinely non-obvious context: the Google calendar itself is untouched and only Luca's selection changes, which materially recalibrates how destructive the agent treats the call. It also discloses required scopes and the idempotency-key requirement for safe retries.

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-loads the most decision-relevant fact (the Google calendar is not deleted) before operational metadata. Slightly padded by infrastructure boilerplate (scope strings, 'data sensitivity: redacted'), but every block is scannable and 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?

With annotations covering safety and an output schema present, the description supplies the remaining essentials for a mutation tool: scopes, idempotency guidance, workspace targeting, and the true blast radius. Minor gap is the absence of an explicit pointer to the inverse calendars_select sibling.

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 75% and the schema already documents workspaceId, workspaceSlug, and idempotencyKey with essentially the same wording the description repeats. The body/calendarId parameter carries no added semantic detail in the description, so this is the baseline 3 where 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?

The opening sentence states a specific action (stop using a calendar) and narrows the resource scope to conflict checks and the booking destination, which cleanly distinguishes it from the inverse sibling luca_bookings_calendars_select. An agent knows exactly what state change this performs without opening the 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?

The description gives clear context for when the operation applies (removing a calendar from conflict checks or as booking destination) plus operational prerequisites (bookings:write, luca:queue_ops scopes, idempotency key, workspace override). It stops short of explicitly naming the alternative tools (e.g., calendars_select for the inverse action), so exclusions are 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?

Adds substantial context beyond annotations: required scopes (bookings:write, luca:queue_ops), the 400/409 failure modes, and the idempotency-key requirement with fallback generation. Annotations already cover safety/mutability, so this is genuine additive value rather than repetition.

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-loads the core purpose before the operational metadata. The scope/idempotency/workspace lines are terse and each carries distinct information, though the block form is slightly dense.

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 an output schema present, return values needn't be described. The description covers purpose, preconditions, error codes, scopes, and idempotency, leaving little an agent needs missing 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 coverage is 75% with descriptions on workspaceId, workspaceSlug, and idempotencyKey. The description reinforces the workspace override semantics and explains idempotencyKey's retry purpose, adding meaning beyond the nested body fields.

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: adding or updating a calendar selection with two distinct modes (conflict checks or write destination). It clearly identifies the resource, though it doesn't explicitly contrast with the sibling luca_bookings_calendars_remove that also operates on this resource.

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?

Explains the two use modes (conflict checks vs. destination) and gives concrete preconditions: the destination must be writable, a read-only calendar returns 400, a Google connection needing attention returns 409. No explicit when-not or named alternative tool, 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?

Annotations already declare destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is partly covered. The description still adds genuinely new context: required OAuth scopes, the data-sensitivity level, the hard confirm gate, and the server-generated idempotency key fallback. It stops short of saying whether a cancellation can be undone or what downstream effects it triggers.

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-loads the one-line purpose, then stacks short metadata lines (operation, scopes, idempotency, confirm, workspace) that are each scannable. Slight redundancy with the schema's own confirm and idempotencyKey descriptions, but no wasted prose.

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 an output schema present, the description covers auth, the confirm gate, retry semantics and workspace scoping, so an agent has enough to call it correctly. The main remaining gap is the real-world consequence detail (reversibility, notifications/automations fired on cancel).

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 80%, so the baseline is 3, and the description earns a point above it by explaining that idempotencyKey exists for safe retries (or is auto-generated) and that workspaceId/workspaceSlug override the environment default. The id parameter's UUID semantics remain schema-only, but that is adequately documented there.

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 ("Cancel a booking") and pins it to the concrete operation DELETE /api/bookings/{id}. Against siblings like luca_bookings_update, luca_bookings_get, and luca_bookings_lifecycle_resolution, an agent can immediately tell this is the cancellation path.

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 clear preconditions for calling it (required scopes, Idempotency-Key, mandatory confirm: true) and explains how to target a non-default workspace. It does not, however, name an alternative for related intents such as rescheduling or lifecycle resolution, so the agent must infer when cancellation is the wrong choice.

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/openWorld, but the description adds real operational context: the strict confirm:true gate with rejection on omission, server-side idempotency-key generation for safe retries, required write scopes, and data-sensitivity level. This materially exceeds what the annotations convey and is consistent with them.

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 purpose, then broken into readable operational lines (endpoint, scopes, idempotency, confirm). Slightly verbose — the 'Destructive: has a real-world side effect' sentence restates annotation/schema content — but no serious waste.

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

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

For a destructive create with nested body, 5 params, and an output schema, the description covers the essentials: required body fields, confirm gate, idempotency, and workspace targeting. Return values need not be explained given the output schema; only sibling differentiation is thin.

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 schema coverage at 80% the schema already documents confirm, idempotencyKey, and workspace overrides, so the baseline would be 3. The description adds value by naming the required body fields (leadId, slotAt), the retry-key behavior, and the workspace-override intent, pushing it above 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?

States a specific verb and resource ('Create a provider-neutral booking record') that distinguishes record creation from read tools like luca_bookings_get/list. It does not, however, distinguish itself from the higher-level action siblings luca_book_call or luca_reschedule_call, and the generic title 'Book a call' overlaps with them.

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

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

The description gives prerequisites (confirm: true, idempotencyKey) and workspace-override context, which implies when the tool is callable. But it never states when to choose this vs. alternatives such as luca_book_call or luca_bookings_update, leaving sibling routing 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 already declare readOnly/not-destructive/idempotent, so the description adds real value beyond them: the underlying operation (GET /api/bookings/{id}), required scopes (bookings:read, luca:read), the 'full_content' data sensitivity, and an explicit idempotency note. It omits pagination/field-expansion behavior, but the safety and auth profile is well covered.

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 payload of the tool in one sentence, followed by clearly labeled metadata lines. Every line carries operational information; no filler or duplicated prose. Slightly boilerplate-heavy but appropriately sized.

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?

An output schema exists, so return values need not be explained, and the description supplies the operation, auth scopes, sensitivity, and workspace-override context. Only the ambiguity around workspaceId vs workspaceSlug precedence and item-level filtering keeps it short of full completeness.

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 67%, and the description's only parameter-relevant line restates the workspaceId/workspaceSlug override that the schema already documents. It adds nothing for 'id' (uuid/pattern) and doesn't clarify precedence when both workspaceId and workspaceSlug are supplied.

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 ('Read one booking') and enumerates the returned facets (slot, status, provider, lead). The word 'one' distinguishes it from the sibling luca_bookings_list, though no sibling is named 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 implied by the required 'id' and the single-item framing, but there is no explicit when-to-use guidance, no statement of when to prefer luca_bookings_list or luca_bookings_brief instead, and no exclusions. The workspace override note concerns parameters, not usage selection.

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

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

Adds substantial value beyond annotations: endpoint path, required scopes/bookings:write, OAuth scope, data sensitivity, and the fact that links are revocable and that an Idempotency-Key is required. The idempotentHint=false annotation is consistent with the description telling the caller to supply a key for safe retries, not contradicted by 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?

Purpose is front-loaded in the first sentence, with operational metadata (scopes, idempotency, workspace) following efficiently. Slightly dense but every line carries operational weight.

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?

An output schema exists, so return values need no explanation, and the description covers auth, idempotency, and workspace scoping for a mutating tool. The only meaningful gap is the lifetime semantics of the generated links, which are left to the schema's numeric bounds.

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 60%. The description clarifies idempotencyKey and workspaceId/workspaceSlug beyond the schema, but says nothing about expiresInHours (default 168, max 720), which is the one body parameter lacking a schema description and matters for guest link lifetime.

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 (mint/create) plus resource (guest reschedule/cancel links) and the business reason (let a lead move the call without an account). It is clearly distinguishable from the sibling luca_bookings_guest_links_revoke and from generic booking mutations.

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?

Clear context for use: scopes, workspace override, and retry behavior are spelled out. It does not explicitly name when NOT to use it versus revoke/update alternatives, so it stays 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?

Annotations already declare destructive=true, readOnly=false, idempotent=false, so the safety profile is covered. The description adds real context beyond that: required scopes, that an Idempotency-Key is required for safe retries, that the server generates one if omitted, and the workspace-override behavior. This is meaningful operational detail for a destructive mutation.

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 destructive purpose is front-loaded in one sharp sentence, followed by compact metadata lines (operation, scopes, idempotency, workspace). Mostly earned, though the scope/metadata boilerplate is dense and slightly repetitive of the schema.

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

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

With an output schema present, return values need not be explained, and annotations carry the safety profile. The description supplies scopes, idempotency, and workspace override, so an agent has what it needs. Only minor gap is the absence of any when-to-use framing.

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 75%, so the schema already documents workspaceId, workspaceSlug, and idempotencyKey. The description largely restates the idempotency and workspace-override semantics rather than adding new syntax or format meaning; the required `id` (booking id) is never clarified but is self-evident. Baseline 3 is appropriate.

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

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

The description uses a specific verb+resource ('Revoke/kill ... guest links on a booking') and states the bulk scope ('every outstanding guest link ... at once'). It is trivially distinguishable from the sibling luca_bookings_guest_links_create, and the underlying operation (DELETE /api/bookings/{id}/guest-links) is named 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 by the delete semantics and the 'at once' bulk phrasing. There is no explicit when-to-use or when-not guidance, and no routing to an alternative (e.g. whether individual link revocation exists). Adequate but leaves 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 cover readOnly, idempotent and non-destructive, so the bar is lower. The description still adds real operational context: required scopes (bookings:read, luca:read), full_content data sensitivity, and that no idempotency key is needed. It does not disclose pagination, result volume, or whether the disagreements are pre-filtered by severity.

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 distinguishing definition is front-loaded in one sentence, followed by a compact metadata block (endpoint, scopes, idempotency, workspace override). Most lines earn their place, though 'Does not require idempotency' is partly redundant against the idempotentHint annotation.

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 an output schema present, return values need not be described, and the description supplies the endpoint, auth scopes, sensitivity level and workspace override behavior. What remains thin is the relationship to the resolution/retry siblings and any hint about how many items or how often to re-check.

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

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

Schema coverage is 100%, so both optional parameters are already documented, giving a baseline of 3. The description's 'Use workspaceId or workspaceSlug to override the default workspace configured by environment' adds the useful fact that a default exists and these are overrides, but nothing about precedence when both are supplied.

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 precise verb+resource and a genuinely distinguishing scope: bookings where Luca's record and the provider's disagree and a human must decide. That clearly separates it from luca_bookings_list and luca_bookings_needs_outcome. It stops short of naming the sibling it feeds into (luca_bookings_lifecycle_resolution), so it is not 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?

Usage is only implied: the agent can infer this is the read step before calling luca_bookings_lifecycle_resolution, but the description never says when to use this versus that resolution tool, nor whether it should be polled or is event-driven. No explicit when/when-not guidance is present.

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?

Adds real context beyond the annotations: required scope bookings:write, luca:queue_ops OAuth scope, full_content sensitivity, the Idempotency-Key requirement, and the mandatory confirm:true gate. These are operationally important disclosures the annotations alone (readOnly=false, destructive=true, idempotent=false) do not convey. It does not describe reversibility or what state changes actually occur.

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 intent sentence is front-loaded and the remaining operational requirements are broken into short, scannable lines. The API path and scope/sensitivity metadata are somewhat boilerplate-heavy but still earn their place for a write operation.

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?

An output schema exists, so return values need no explanation. For a destructive booking mutation with annotations, the description covers auth, idempotency, confirmation and workspace scoping, leaving only the precise body-shape semantics under-specified.

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 67%, so the schema already documents confirm, idempotencyKey and the workspace overrides, which the description largely restates. The core `body` parameter (status/action/reason enums) has no schema description, and the description's three-option phrasing only loosely maps to it, so it does not compensate for that 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?

States a specific verb+resource ("Settle one booking whose record disagrees with the provider's") and enumerates three resolution outcomes, which distinguishes it from generic siblings like luca_bookings_update and luca_bookings_provider_sync_retry. However, the listed options ("retry the sync, dismiss the duplicate, keep Luca's version") map imperfectly onto the schema's actual enums (action=dismiss_duplicate, status=confirmed/cancelled/completed/no_show), so the naming of the alternatives is slightly imprecise.

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 an implied trigger condition (a booking whose record disagrees with the provider's) but never names a competing tool or says when NOT to use this one, even though luca_bookings_provider_sync_retry and luca_bookings_update are obvious neighbors. Usage is inferable but not routed.

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 readOnly/idempotent/non-destructive, and the description adds genuinely non-structured context: required scopes, 'data sensitivity: full_content', and the workspace-override default. It omits any note on pagination/truncation behavior at the description level, though maxPages in the schema partially covers that.

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 purpose, then compact metadata lines. Some lines ('Does not require idempotency') are near-redundant with the idempotentHint annotation, but nothing is verbose.

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 annotations, an output schema, and nested query schema already present, the description's remaining job is auth/scope and default-workspace context, which it supplies. The one real gap is filter value semantics for status and upcoming.

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 75% and the description names limit, cursor, status, upcoming, workspaceId and workspaceSlug, but never explains what values status/upcoming accept (no enums) and omits leadId entirely. It repeats schema-known parameter names rather than adding filter semantics.

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 ('List bookings') and even names the underlying operation (GET /api/bookings), so the agent knows exactly what happens. It does not, however, distinguish itself from nearby siblings such as luca_bookings_brief, luca_bookings_get, or luca_bookings_lifecycle_attention.

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 useful preconditions (scope bookings:read, luca:read) and tells the agent how to override the default workspace, but it never says when to choose this list over sibling retrieval tools like luca_bookings_get or luca_bookings_brief. Usage is implied rather than stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description still adds real value beyond them: that conflicts are pre-filtered out of the results, the OAuth scope requirement (luca:read), the data-sensitivity/redaction note, and that no idempotency key is needed.

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 key capability is front-loaded in the first sentence and the remaining lines are short metadata bullets. The 'Luca operation' and 'Does not require idempotency' lines are borderline boilerplate but compact, so nothing meaningfully bloats the definition.

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?

An output schema exists, so return values need no explanation, and annotations plus the scope/workspace notes cover most operational prerequisites. What is missing is the disambiguation from luca_bookings_availability and any indication of time-range defaults or limits for a slot-listing call.

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 67%, so the schema does much of the work. The description explains the workspaceId/workspaceSlug override semantics and the environment-configured default, which goes slightly beyond the schema's terse 'Optional Luca workspace id override'. The required nested query fields (bookingTypeId, timezone, start/end) receive no explanation of format or defaults.

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 and resource — 'List open slots for one of Luca's own call types' — and adds the meaningful qualifier that calendar conflicts are already removed. It is clear on its own, but it never differentiates itself from the very similar sibling luca_bookings_availability, so an agent must guess which of the two to call.

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 ('list open slots for one of Luca's own call types'), and the description adds prerequisite context via required scopes. However there is no explicit when-to-use vs when-not guidance and no mention of the near-identical luca_bookings_availability alternative, which is the single most important routing decision here.

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 and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: required OAuth scopes, 'data sensitivity: full_content', and the fact that no idempotency key is required. The phrase 'Does not require idempotency' sits in mild tension with idempotentHint=true (one describes the caller's obligation, the other the operation's nature), but it is not a contradiction.

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

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

The purpose sentence is front-loaded and the operational metadata is compact and scannable. The 'Does not require idempotency' line is the one near-filler item, since annotations already carry idempotency semantics, but overall there is little waste.

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

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

An output schema exists, so return values need not be described, and the description covers the remaining unknowns: auth scopes, sensitivity level, read-only nature, and workspace defaulting. Pagination or result-size behavior for this list is not mentioned, which is the only notable gap for a read-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?

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema lacks: workspaceId/workspaceSlug are overrides of a default workspace configured by the environment. That fallback behavior is genuinely useful for deciding whether to pass either parameter at all.

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 with a precise scope: 'List attended calls with no outcome recorded yet,' which cleanly separates it from luca_bookings_list (all bookings), luca_bookings_outcome_get (one booking's outcome), and luca_bookings_outcome_record (the write side). 'The work list for closing revenue attribution' adds the business intent, so an agent knows what this list is for without opening the 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?

Usage context is clear: this is the work list an agent pulls when it needs to close out revenue attribution, and the required scopes (bookings:read, luca:read) are stated as prerequisites. It does not name alternatives or state when not to use it (e.g. versus luca_call_events_needing_feedback), so it stops short of 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description still adds real context by listing required scopes (bookings:read, luca:read), noting data sensitivity is redacted, and confirming no idempotency key is needed. It does not describe error or not-found behavior, but the added auth/sensitivity detail is genuinely beyond the structured fields.

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 purpose sentence is front-loaded, followed by operation path, scopes, idempotency and workspace override as short scannable lines. Slightly boilerplate-heavy, but every line carries information and 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?

An output schema exists, so return values need not be explained, and annotations carry the safety profile. The description supplies the remaining essentials an agent needs: auth scopes, sensitivity, idempotency posture and workspace override semantics. Only minor gaps remain (no explicit sibling routing), so it is complete enough to call correctly.

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

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

Schema coverage is 67%: workspaceId and workspaceSlug are already documented as 'Optional Luca workspace ... override'. The description restates the override and adds the useful fact that the fallback is the environment-configured default workspace, but the required `id` parameter carries no description anywhere. Net value over the schema is marginal, matching the baseline 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?

States a specific verb and resource ('Read where the sale stands on a booking') and adds the useful detail that it also returns 'the version you send back to correct it', which points at the optimistic-concurrency token consumed by luca_bookings_outcome_record. It stops short of naming sibling tools like outcome_history or outcome_record, so an agent must infer the boundary rather than read 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?

The mention of 'the version you send back to correct it' implicitly signals the read-before-update workflow, and the workspace override note gives a usage condition. However, there is no explicit when-to-use guidance or routing versus the many sibling outcome tools (history, record, reasons_list, needs_outcome), leaving alternatives 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 already declare readOnly, idempotent, non-destructive, so the safety bar is low; the description still adds real value with 'Corrections append rather than overwrite' and the scope/data-sensitivity disclosures. It does not mention pagination or result volume for an 'every outcome ever' 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?

Front-loads the core behavior in the first sentence, then layers operation/scope/workspace metadata compactly. Slightly boilerplate-heavy but every line carries actionable 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?

An output schema exists, so return values needn't be described; scopes, auth, and workspace resolution are covered. Only the absence of pagination/volume hints for a potentially unbounded history leaves a minor gap.

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

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

Schema coverage is 67% (id is undocumented, workspace params have descriptions), so the schema does part of the work. The description explains the workspaceId/workspaceSlug override against the environment-configured default, adding meaning the schema alone doesn't 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 resource ('Read every outcome ever recorded on a booking, in order') and adds the append-only nuance. It is clearly distinguishable in intent, though it does not explicitly name the nearest sibling (luca_bookings_outcome_get) to contrast history-vs-current outcome.

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?

Provides operational context (required scopes, workspace override, idempotency not required) but gives no explicit when-to-use/when-not guidance versus outcome_get, outcome_record, or outcome_reasons_list. Usage is only implied by the 'history' framing.

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?

Going beyond the annotations, the description discloses a concrete failure mode (409 when the code is already in use), the required OAuth scopes (bookings:write, luca:queue_ops), and idempotency-key handling for retries. This is meaningful behavioral context that the structured fields do not carry.

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 core purpose is front-loaded in the first sentence, followed by compact operation metadata (endpoint, scopes, idempotency, workspace override). Well structured and largely waste-free, though the metadata lines are somewhat boilerplate.

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 an output schema present, return values need not be described, and the definition covers scopes, idempotency, conflict behavior, and workspace targeting. It omits a few body fields and any note on the kind enum's meaning, but is sufficient to invoke the tool correctly.

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

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

Schema description coverage is 75%, so the schema largely documents the parameters. The description adds useful semantics to 'code' (uniqueness/409) and 'label' (workspace's own wording) and explains the workspaceId/workspaceSlug override, but says nothing about kind, displayOrder, or bookingTypeId.

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: 'Add a lost-sale or cancellation reason in the workspace's own wording.' This clearly distinguishes the create action from siblings like outcome_reasons_list and outcome_reasons_update, though it doesn't explicitly call those siblings out.

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 present but indirect: it explains the 409 behavior on duplicate codes, when to supply an idempotencyKey for safe retries, and how to override the default workspace. It never states when to use this tool versus the update/list siblings or what preconditions (e.g., existing code set) apply.

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 read-only, idempotent, non-destructive, non-open-world. The description adds scope requirements (bookings:read, luca:read), data sensitivity, and the absence of an idempotency requirement, which is real context beyond the structured annotations. No caveats about pagination or result limits are given.

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 purpose is front-loaded in a single sentence, followed by the usage hint and compact operation metadata. The boilerplate scope/idempotency lines are justified as they carry information absent from annotations, though 'Does not require idempotency' borders on redundant for a GET.

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?

Output schema exists so return values need not be described, and the description covers auth scopes, workspace override, and safety. What is missing is any statement of the shape or size of the returned reason list and the meaning of the kind filter's third value.

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%: workspaceId and workspaceSlug carry their own schema descriptions, and the description reinforces the override behavior. The `kind` query parameter (lost_sale/cancelled_call/no_show) has no schema description, and the description only implicitly gestures at two of the three values, leaving no_show undocumented anywhere.

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 ('List the reasons a sale can be lost or a call cancelled'), which cleanly separates this reference-list tool from luca_bookings_outcome_reasons_create/update. It stops short of 5 because the schema's third enum value, no_show, is never mentioned, so the enumerated scope is under-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?

'Use one of these codes when recording an outcome' gives a concrete downstream usage context that tells the agent why to call it before luca_bookings_outcome_record. It does not name that sibling explicitly or state when not to call it, so it falls short of full 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?

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds real value: archiving's non-destructive effect on existing outcomes, the required idempotency key with retry semantics, required scopes, and data sensitivity. That is meaningful behavioral context beyond the annotation flags.

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 functional sentence is front-loaded ahead of the operational metadata block, and each line earns its place. The scopes/sensitivity lines are dense but relevant to correct invocation.

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

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

With an output schema present and annotations covering the safety profile, the description supplies the remaining essentials: mutation semantics, idempotency requirement, auth scopes, and workspace override. Only the body field mapping is left implicit.

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 60%, and the description implicitly maps its verbs to the body fields (label=rename, displayOrder=reorder, active=archive) without naming them, and restates the workspaceId/workspaceSlug/idempotencyKey semantics already documented in the schema. Adequate but adds little beyond 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?

States specific verbs (rename, reorder, archive) against a specific resource (an outcome reason), and clarifies the archive semantics. An agent can distinguish this from siblings like luca_bookings_outcome_reasons_create or _list 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?

The description explains what archiving does (hides from picker, leaves recorded outcomes alone), which implies when to use it, but gives no explicit when-to-use/when-not guidance or named alternatives. Usage must be inferred from the operation list.

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

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

Beyond the annotations it discloses that won/lost can propagate to a CRM deal stage, that the call is rejected without confirm, that a stale expectedVersion yields a 409 carrying the current version, and that an Idempotency-Key is required but auto-generated if omitted. It also states required scopes (bookings:write, luca:queue_ops) and redacted data sensitivity.

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 and the metadata block is scannable. However, the confirm/CRM-deal point is stated twice (once in the opening, once in the 'Destructive when...' block), which is mild redundancy in an otherwise tight description.

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, versioned, authenticated write with an output schema present, the description covers the side effects, confirmation gate, concurrency control, idempotency, and workspace scoping. Nothing an agent needs to invoke it correctly is missing, and return values are correctly left to the output schema.

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

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

With 67% schema coverage, the description carries real weight: it explains confirm's rejection behavior, expectedVersion's 409/stale semantics, idempotencyKey's retry role, and the workspaceId/workspaceSlug override. Body-level fields (amountMinor, currency, lossReasonDefinitionId) are only implied by the outcome enumeration.

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 opening sentence names a specific verb and resource and enumerates the three outcome states ('won, lost with a reason, or still open'), so the agent knows exactly what is being written. It does not explicitly name the sibling it differs from (e.g. luca_bookings_outcome_get, luca_bookings_outcome_history, or luca_call_events_undo_outcome), which keeps it 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 conditional guidance: pass confirm: true for won/lost because those touch a connected CRM deal, and pass expectedVersion when correcting a prior outcome. It does not say when to prefer this over outcome_history/undo_outcome, so exclusions and alternatives are absent.

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, openWorld), and the description adds value beyond them: required scopes (bookings:read, luca:read), 'data sensitivity: redacted' for the returned data, and the workspace-override behavior. 'Does not require idempotency' is not a contradiction of idempotentHint=true (it means no idempotency key is needed), though the phrasing is loose.

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 sentence and the operational metadata is compressed into short labeled lines. There is mild boilerplate redundancy between 'Required scopes: bookings:read' and 'Required OAuth scope: luca:read', 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?

An output schema exists, so return-value shape needn't be documented, and annotations carry the safety profile. Combined with scopes, sensitivity level, and workspace-override semantics, the agent has enough to invoke it correctly; only the lack of routing guidance relative to sibling list tools leaves a gap.

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

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

Schema coverage is 67%: both workspace parameters carry their own descriptions, while the required `provider` enum (manual, calendly, cal_com, google_calendar, iclosed, gohighlevel) is undocumented. The description explains the meaning of the workspace override ('the default workspace configured by environment') but adds nothing about the provider enum values.

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 concrete resource ('the event types and calendars in one connected provider account'), so an agent knows what data comes back. It doesn't distinguish itself from sibling readers such as luca_bookings_providers_list, luca_bookings_types_list, or luca_bookings_calendars_list, and the 'list' framing sits awkwardly against the title 'Get a booking provider'.

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 instruction is 'Use workspaceId or workspaceSlug to override the default workspace configured by environment,' which is real but narrow guidance. Nothing tells the agent when to call this instead of the providers/types/calendars list tools, so selection guidance is only implied.

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, openWorldHint and destructiveHint, so the safety profile is covered. The description adds genuinely new operational context: the underlying GET endpoint, the required bookings:read and luca:read scopes, and the 'redacted' data-sensitivity classification, which matters for an agent reasoning about what it may see.

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 purpose is front-loaded in the first line, followed by a compact block of endpoint, scope, idempotency and workspace notes. The 'Does not require idempotency' line is the weakest, but the metadata lines are terse and each carries an actionable fact.

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?

An output schema exists, so return values need not be described, and the annotations carry the safety profile. The description still supplies endpoint, auth scopes, data sensitivity and the workspace-override rule, leaving nothing an agent needs to invoke the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description goes slightly beyond the schema by explaining that workspaceId/workspaceSlug override a default workspace 'configured by environment', which tells the agent why these params exist rather than just what they are.

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 opening sentence names a specific verb and resource ('List every booking provider') and then extends scope to include capability and connection health, which lets an agent distinguish it from the sibling luca_bookings_providers_get without opening either 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?

Usage is only implied: an agent can infer this is the call for enumerating providers and their health, and the last line explains how to override the environment-default workspace. There is no explicit when-to-use versus luca_bookings_providers_get, luca_bookings_provider_sync_retry, or the calendars list 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?

Goes well beyond the annotations by disclosing permanent-failure 409 semantics, the idempotency-key generation fallback, required OAuth scopes, data sensitivity, and the confirm: true gate. Annotations already flag destructive/openWorld, and the description adds real operational context on top.

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 and failure semantics are front-loaded, followed by structured auth and parameter notes. Slightly boilerplate-flavored (scope lines, workspace override) but each line carries actionable 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 an output schema present and annotations covering the safety profile, the description covers what an agent needs: what it does, the confirm requirement, idempotency, and the 409 outcome. Only marginally missing is guidance on success side effects or preconditions of the retry.

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 80%, so the schema already documents confirm, workspaceId, workspaceSlug and idempotencyKey. The description mostly restates those in prose (server-generated key, workspace override) without adding format or behavioral detail the schema lacks.

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?

Starts with a specific verb+resource ('Retry a failed write-back to the booking provider') and names the exact endpoint, making it unmistakable from siblings like luca_bookings_update or luca_bookings_cancel.

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 phrase 'retry a failed write-back' clearly scopes when to use it, and the 409 behavior tells the agent when retrying is pointless. It stops short of naming an alternative tool or stating preconditions such as verifying the booking is actually in a failed state.

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 and non-destructive, so the safety profile is covered. The description adds value beyond them by disclosing required scopes, the redacted data-sensitivity level, and that idempotency keys are not required, all of which affect how the call should be made.

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 primary operation sentence is front-loaded, followed by compact metadata lines (operation, scopes, idempotency, workspace). Slightly boilerplate but every line carries operational meaning and 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?

An output schema exists, so return values need not be described. For a read-only list tool the description covers scope, auth, sensitivity and workspace targeting; the only residual gap is the lack of a stated when-to-use versus the add/remove siblings.

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