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 declare read-only, idempotent, non-destructive, closed-world behavior. The description adds useful operational context: the underlying GET endpoint, required OAuth scopes, and redacted data sensitivity. It does not describe return values, 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 front-loads the metric surface and then adds endpoint, scope, and workspace override details. The long metric list is dense but justified for an analytics tool, and no sentence is obviously 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?

For a read-only analytics endpoint with annotations and an output schema, the description covers the metric surface and auth requirements well. However, it leaves query-parameter interaction and sibling selection implicit, so an agent still needs to infer some invocation details.

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 query object is nested, yet the description only mentions 'for a period' and workspace overrides. It does not explain how start and end interact with period, nor what the channel filter does, leaving the schema to carry most parameter meaning.

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 analytics resource (post-call intelligence) and enumerates the metrics it returns, so the agent can tell what data it produces. It does not explicitly distinguish itself from the closely named luca_analytics_call_intelligence_calls sibling, leaving some ambiguity about aggregate vs per-call views.

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

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

The description implies usage through the metric list and period/channel context, but it never states when to choose this tool over nearby analytics siblings such as luca_analytics_funnel, luca_analytics_revenue, or luca_analytics_call_intelligence_calls. Usage is inferred rather than explicitly 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 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added value is telling the agent this is a composite that fans out to seven reads in one call — i.e. a heavier, broad-result operation. It does not mention latency, cost, or whether any read can be skipped, which would complete the picture.

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 purpose, then the usage rule, then an example — a sensible order with no filler. The seven-item enumeration makes the first sentence dense, but each item earns its place by telling the agent what data comes back.

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?

Return values are covered by the existing output schema and the safety profile by annotations, so the description only needed to state purpose, scope of aggregation, and when to pick it — all present. Nothing an agent needs in order to call this 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 100% and the schema already explains that period scopes six reads while forecast is point-in-time, and that question is metadata only. The description's example call ({question, period}) adds a little practical framing but no semantics beyond the schema, 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 job ('Answer a specific business question by composing all seven analytics reads in one call') and then enumerates exactly which seven reads are aggregated. This makes it immediately distinguishable from the individual analytics siblings like luca_analytics_funnel or luca_analytics_revenue.

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 selection rule — use it when the coach asks a specific question needing several numbers side by side, 'rather than the fixed weekly report' — and provides a concrete call example. The gap is that it never names the single-metric siblings (luca_analytics_rollup, the individual analytics reads) as the alternative for simple one-number questions.

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?

Annotations already flag destructive/openWorld/non-idempotent, but the description adds what those flags actually mean here: it reads open slots first, creates a real calendar event, messages the lead, returns open slots instead of booking when the slot is taken, and may be pending while the provider confirms. The confirm:true gating requirement is stated with its precondition (coach approval of this exact slot), which the schema's generic confirm blurb does not 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?

Front-loaded with the action and provider scope, then failure handling, then the confirm gate and alternative tool. Nine sentences is on the long side for a tool description, and the pending-status and retry sentences overlap slightly, but no sentence 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?

A high-stakes mutation with 10 params and 4 required fields; the description covers preconditions, side effects, fallback behavior, retry safety, and the sibling to use instead. Return values are covered by the output schema, so nothing material is 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 100%, so the baseline is 3; the description earns a bump by adding a full example call showing the four required params together and by clarifying that slotAt must match a slot the availability listing returned. It does not add meaning for the less-obvious params (workspaceId/workspaceSlug overrides, timezone), leaving that 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 and resource (book a call on the coach's calendar provider) plus the side effects (provider invites the lead's email, lead gets Luca's confirmation). It also names the providers covered and distinguishes itself from luca_bookings_create, which records calls already on a calendar.

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

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

Explicit about when to call (after the lead agreed to a time and the coach approved this exact slot), when not to (use luca_bookings_create to record an existing call), and what to do on the two failure paths (slot taken → pick from returned slots; slot_not_available on retry → check luca_bookings_list first). It also points to luca_bookings_provider_requests_get for pending confirmations.

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 description's added value is the auth surface: required scopes bookings:read and luca:read, data sensitivity 'redacted', no idempotency key needed, and the fact it falls back to an environment-configured default workspace. It still doesn't describe the returned shape or how availability is computed (calendar sync state, provider differences).

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 actionable sentence is front-loaded, but several lines are generated metadata (Luca operation, required scopes, idempotency boilerplate) that pad the definition. Still efficiently short overall with no filler 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?

With an output schema present, the description needn't explain return values, and it covers purpose, ordering relative to booking, auth scopes, and workspace defaults. The remaining gap is guidance on the filter parameters that drive what slots come back.

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 only start/end carry inline descriptions. The description compensates for workspaceId/workspaceSlug by explaining the default-workspace override, but the nested query parameters (leadId, provider, timezone, calendarId, eventTypeId) are undocumented in both the schema and the description, leaving real gaps.

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 specific verb and resource ('List open slots the coach can actually be booked into'), and 'actually be booked into' distinguishes it from a static schedule listing. It is not explicitly differentiated by name from close siblings like luca_bookings_managed_availability or luca_bookings_types_schedule, which would be needed 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?

'Check this before booking' gives a concrete ordering constraint relative to the write tools (luca_bookings_create, luca_book_call). It does not name when-not to use it or point at luca_bookings_managed_availability / luca_bookings_types_schedule as alternatives for differing needs.

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?

The annotations already declare destructiveHint=true and idempotentHint=true, but the description adds important context: only Luca's selection changes and the Google calendar is untouched. It also discloses required scopes and idempotency-key behavior, which helps the agent understand the side effects and retry semantics.

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 purpose and side-effect clarification, followed by operation metadata and retry/workspace guidance. It is efficient overall, though the metadata lines make it slightly less crisp than a pure prose 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?

With annotations, schema, and an output schema present, the description supplies the key operational context: side effects, scopes, idempotency, and workspace override. It is complete enough for correct invocation, though it could explicitly point to the select/list siblings for related workflows.

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 already documents most parameters. The description reinforces idempotencyKey and workspace override behavior, but it does not add meaning for the required body fields provider and calendarId beyond what is in the schema.

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

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

The description states a specific action and scope: stop using a calendar for conflict checks or as the booking destination. It also clarifies that the Google calendar itself is left alone, distinguishing this from actual calendar deletion and from the sibling selection operation.

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

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

It clearly describes the situation in which to use the tool: when a calendar should no longer be used for conflict checks or as the booking destination. It does not explicitly name luca_bookings_calendars_select as the alternative, but the usage 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 the mutation profile (destructive, idempotent, open-world), so the bar is lower, and the description still adds real value: error semantics (400/409), required scopes, and idempotency-key handling. It does not say what happens to a previously selected destination/conflict calendar when this upsert runs, which is the remaining meaningful 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?

Front-loaded with the behavioral sentence, then a compact block of operational facts (endpoint, scopes, idempotency, workspace override). Every line adds something, though the metadata block is slightly boilerplate-heavy.

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

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

Since an output schema exists, return values need not be explained, and the description covers auth, retries, workspace scoping, and failure codes for a nested-body mutation. It is not fully complete for the complex body schema — the semantics of the required calendar fields are left to the caller to infer.

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?

Top-level params (workspaceId, workspaceSlug, idempotencyKey) are covered by schema descriptions and echoed in the prose. However, the nested body object contains seven required fields with zero property descriptions in the schema, and the description explains none of them — notably accessRole and the distinction between conflictEnabled and defaultDestination, which are only hinted at by the 'conflict checks / destination' framing.

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 pair and resource: 'Add or update a calendar selection', with the two distinct purposes spelled out (conflict checks vs. destination for new bookings). It is clearly distinct from the list/remove siblings by implication, though it never names them 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?

Gives concrete eligibility conditions for the destination role: it must be writable, a read-only calendar returns 400, and a Google connection needing attention returns 409. It also explains the workspace override and idempotency key, though it offers no explicit 'use X instead when...' routing to siblings.

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

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

Goes well beyond the annotations: it explains that external calendars are mutated, that the connected calendar may email the lead (a side effect the agent cannot see from destructiveHint alone), that an Idempotency-Key is required but server-generated if omitted, and that the call is rejected without confirm: true. These are exactly the behavioral facts an agent needs before committing a destructive 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 purpose and the cross-system side effect, then lists operational requirements in a scannable block. There is minor redundancy — the confirm and idempotencyKey rules are repeated in the schema descriptions — but nothing is padded or irrelevant.

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 annotations already cover readOnly/openWorld/idempotent/destructive. What remains thin is the write-side aftermath: whether guest links, reminders, or outcomes tied to the booking are affected. Strong but not exhaustive for a destructive multi-system operation.

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

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

Schema coverage is 80%, so the baseline is 3; the description earns an extra point by restating the confirm gate as a hard rejection condition and explaining the idempotency-key fallback behavior and the workspace default-override semantics. Only the 'id' parameter's meaning is left entirely to the schema, which is acceptable for a path identifier.

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 immediately discloses the downstream consequence: the booking is also cancelled in the connected Google Calendar or Cal.com. This distinguishes it clearly from siblings like luca_bookings_update, luca_reschedule_call, and luca_bookings_get without needing 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?

It gives operational preconditions (bookings:write scope, Idempotency-Key, confirm: true, workspace override) which is useful invocation guidance. However it never says when to choose this over alternatives — e.g. no mention of luca_reschedule_call for moving a booking instead of cancelling, or what to do if the booking is already cancelled. 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 destructiveHint=true and openWorldHint=true, but the description adds genuinely new behavior: required OAuth scope luca:queue_ops, full_content data sensitivity, the Idempotency-Key requirement including server-side generation when omitted, and that the call is rejected without confirm: true. Idempotency behavior in particular is not expressible via the idempotentHint=false 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?

Front-loaded with the core action in sentence one, then organized into short labeled lines for endpoint, scopes, idempotency, confirmation and workspace override. Slight redundancy: the confirm requirement is stated both in the description and in the confirm parameter's schema 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?

An output schema exists, so return values need not be explained, and the top-level parameters are well covered. However the nested body object carries 13 properties (provider, status, timezone, locationType, calendly/provider event IDs) that the description never touches, so an agent gets no guidance on the provider-neutral payload shape beyond the two required fields.

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 almost verbatim as the description restates them. The mention that leadId and slotAt are required just repeats the schema's required array. 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 first sentence states a specific verb and resource ("Create a provider-neutral booking record") and adds the two required body fields. "Provider-neutral" usefully sets it apart from provider-sync siblings like luca_bookings_provider_requests_create, but it never names luca_book_call or luca_reschedule_call, which an agent could easily confuse with this.

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

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

Usage context is implied by the operational requirements (scopes, confirm, workspace override) but there is no explicit when-to-use / when-not-to-use guidance and no routing against the many booking siblings (luca_book_call, luca_bookings_update, luca_bookings_cancel, luca_bookings_guest_links_create). The agent must infer selection from the tool 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 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 flag destructiveHint=true, idempotentHint=true, so the safety profile is covered. The description adds genuinely useful operational context: required scopes (bookings:write, luca:queue_ops), that an Idempotency-Key is mandatory with server-side generation as fallback, and that data is redacted. It stops short of saying whether revocation is reversible or what happens to already-used links, but the additions are substantive.

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 action and its bulk scope are front-loaded in one sentence, followed by compact structured lines for endpoint, scopes, idempotency, and workspace. Every line carries information; the 'data sensitivity: redacted' fragment is the only piece of ambiguous 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, the description needn't explain return values, and it does cover auth scopes, idempotency, workspace targeting, and destructive scope. The remaining gap is outcome semantics—whether previously issued or already-accepted links are also invalidated—but the definition 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 coverage is 75% and the three optional parameters (workspaceId, workspaceSlug, idempotencyKey) each carry their own schema description. The description restates the idempotency-key behavior and workspace override without adding format or precedence rules beyond the schema. Adequate at the baseline, but not additive.

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 verb ('kill'/'revoke'), resource ('guest links'), and scope ('every outstanding ... on a booking at once'), and the DELETE endpoint line pins the exact operation. This clearly separates it from the sibling luca_bookings_guest_links_create.

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 bulk nature ('every outstanding guest link at once') implies when this tool is appropriate, and the workspace-override line tells the agent how to target a non-default workspace. However, there is no explicit when-to-use versus create/update, and no stated preconditions (e.g. what happens if the booking already started). Usage is implied rather than spelled out.

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

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

Annotations already 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/openWorld/idempotent/non-destructive, so the bar is lower, and the description still adds real context: required scopes, redacted data sensitivity, workspace override behavior, and the meaningful detail that calendar conflicts are pre-removed. The line "Does not require idempotency" sits awkwardly beside idempotentHint=true but is about idempotency keys, not the operation's nature, so it reads as redundant rather than 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 in the first sentence, followed by a compact metadata block. The scope/sensitivity lines are boilerplate but each carries actionable constraint information; nothing is padding, though the block format is denser than needed.

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 description covers auth scope, workspace selection, and the conflict-free semantics. The remaining gap is guidance on the two required nested parameters and on choosing this tool over luca_bookings_availability.

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%, so the baseline is roughly met. The description restates the workspaceId/workspaceSlug override that the schema already documents, but says nothing about the nested `query` object's required fields (bookingTypeId, timezone) or what timezone controls — the most error-prone part of the call.

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") scoped to "one of Luca's own call types" and adds the key behavioral qualifier that calendar conflicts are already removed. It does not, however, distinguish itself from the sibling luca_bookings_availability, so an agent still has to infer which availability endpoint applies.

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 is only implied by "for one of Luca's own call types" — an agent can guess this is for Luca-managed booking types rather than externally synced calendars, but the description never says when not to use it or names luca_bookings_availability as the alternative. No prerequisites or exclusions are 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 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?

Adds substantial context beyond the annotations: the invite is emailed to the lead, the lead also receives Luca's confirmation, the response is typically pending, and a race condition returns 409 slot_unavailable. It also restates the confirm:true and idempotency requirements in the flow of 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 core booking instruction is front-loaded in the first sentence, and error/retry guidance follows. It is dense and somewhat run-on, particularly the first sentence, but every clause carries operational 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 destructive, open-world, non-idempotent mutation with an output schema, the description covers the async pending state, the required re-read tool, the conflict error, idempotency, confirmation, and workspace overrides. An agent has everything needed to call and follow up 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 80%, so the baseline is 3, and the description adds real meaning by explaining that slotId, startsAt, endsAt, and timezone must come from a read of exactly that slot's window because the id is tied to the window. It does not explain the leadId/bookingTypeId/inviteeEmail relationship, but those are largely self-evident UUID/email 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 (book one exact slot on the coach's Calendly/Cal.com/Google Calendar) and ties it to the exact upstream read (luca_bookings_managed_availability), which differentiates it from siblings like luca_bookings_create and luca_book_call.

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