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

Annotations only indicate non-read-only/non-idempotent, so the description adds meaningful behavioral context: a new event is created, a JSON dict with the event id is returned, and descriptions should carry Notion links when scheduling task blocks. No contradiction with 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 two-sentence purpose/when-to-use section, structured Args block, and Returns line are front-loaded and contain no filler. Every line earns its place, and the argument details are easy to scan.

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

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

The description covers the call's purpose, parameters, task-link convention, defaults, and returned id, making it complete for a create operation. It would be stronger if it named the sibling schedule_task_block as an alternative for automatic scheduling, but nothing essential is missing.

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

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

The Args section lists all six params with types, default calendar_id, and the Notion-URL instruction for description. Given the low schema-description coverage signal for the top-level params object, this fully compensates and adds task-workflow meaning beyond plain property names.

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: 'Create a new Google Calendar event.' It distinguishes the tool from update/delete/get siblings and adds the Notion-task work-block convention, so an agent understands exactly what action this tool performs.

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 concrete context for use — creating work blocks for Notion tasks and linking the Notion URL. It does not explicitly state when not to use this tool or compare it with schedule_task_block, but the creation context is clear enough to route basic calls.

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

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

Annotations already mark the tool as destructive, but the description adds meaningful context by stating the deletion is permanent and irreversible, and by advising confirmation beforehand. It addresses what gets destroyed and the consequence, which goes slightly beyond the destructiveHint flag.

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

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

The description is compact and well-structured, with the key warning front-loaded before the parameter list. The Args section is somewhat redundant with the schema, but the overall length is appropriate and every section is immediately useful.

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

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

For a simple destructive delete operation, the description covers the action, irreversibility, prerequisite verification, parameter meanings, and return type. The schema handles the default and required details, so nothing essential is missing for an agent 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?

The description repeats the parameter names and basic meanings already present in the input schema, but it adds little beyond that. It does not specify that calendar_id has a default of 'primary', nor does it clarify optionality versus requiredness beyond what the schema already provides.

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 'Permanently delete a Google Calendar event,' a specific verb and resource that unambiguously states the action. It clearly distinguishes this from sibling tools like gcal_create_event, gcal_update_event, and gcal_get_events.

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 warns that the action cannot be undone and explicitly instructs the agent to confirm the event ID with gcal_get_events before deleting. It does not enumerate explicit when-not-to-use cases or alternatives, but the irreversibility warning and prerequisite are strong usage guidance for a destructive tool.

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 mark this as read-only and non-destructive, and the description adds meaningful behavior: it returns all slots with at least the requested duration and describes the JSON array output with start/end ISO datetimes. It also clarifies that earliest/latest hours constrain slot start/end boundaries.

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

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

The description is front-loaded with the core purpose and use case, then gives a structured Args/Returns breakdown. The Args list repeats some schema information, but it is organized and compact enough to scan quickly.

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 scheduling tool with five parameters, the description covers inputs, output format, and slot semantics. It does not discuss timezone handling, working-hours assumptions, or why a slot might be considered unavailable, but those are not essential for basic 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?

Despite the reported 0% schema coverage, the description's Args section documents each parameter, including boundary semantics for earliest_hour and latest_hour and the role of calendar_id. It mostly mirrors the schema metadata, but it adds explicit 'don't suggest before/after' wording that helps an agent call the tool correctly.

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

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

The description opens with a specific verb and object — find available time slots — and states the two central constraints (duration, date). It also clarifies the result semantics: all slots with at least the requested duration, which distinguishes this from gcal_get_events or schedule_find_conflicts.

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 explicitly identifies scheduling work blocks, appointments, or time-bound tasks as the context, which is clear guidance for when to use it. However, it does not name sibling alternatives or state when not to use it, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds useful context: returns event IDs, titles, times, descriptions, and locations, and explains how IDs connect to other tools. It does not describe ordering or timezone behavior, but this is not critical for safe invocation.

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?

Well-organized with a front-loaded purpose sentence, followed by concise Args and Returns sections. Every sentence adds value, including the downstream ID usage 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?

Given the presence of an output schema and safety annotations, the description covers purpose, all parameters, and the return shape. Nothing critical is missing for an agent to select and call this 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?

The description documents all nested parameters with defaults and meanings, compensating for the low schema coverage signal. It could add examples or the max_results maximum, but the provided semantics are sufficient for correct invocation.

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: 'Fetch Google Calendar events within a date range.' It also enumerates the returned fields, making it easy to distinguish from siblings like gcal_list_calendars and gcal_find_free_slots.

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 clear context for when to use it: to retrieve events in a range and obtain event IDs for later update/delete operations. It does not explicitly mention alternatives or when-not-to-use conditions, but the intended workflow 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 readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the scope of 'all' calendars accessible to the user and states the return shape, but does not disclose potential edge cases like empty results or pagination. This is moderate value beyond annotations.

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

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

The description is two short, focused sections: one sentence for the action and one for the return type. Every word earns its place, with the core purpose front-loaded and no filler.

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

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

For a zero-parameter read-only list tool with an output schema, the description is fully sufficient. It tells the agent what action is performed and what is returned, and the annotations confirm non-destructiveness.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameters, and the 'all calendars' wording clarifies the implicit scope 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?

The description states a specific verb and resource: 'List all Google Calendars the user has access to.' It is unambiguous and clearly distinct from sibling tools that deal with events, appointments, or tasks, even without naming them.

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

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

The intended use case is implied rather than explicit: if you need to enumerate the user's accessible calendars, this is the tool. There is no direct guidance about when to prefer it over sibling tools or mention of exclusions, so it stops at implied usage.

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

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

Annotations already establish readOnly=false, idempotent=true, and destructive=false. The description adds the critical nuance 'Only provided fields are changed; omitted fields remain as-is,' which prevents an agent from assuming unlisted fields get cleared, and it discloses the return contract ('JSON dict of the updated event'). This is consistent with all three annotation hints, so no 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 comes first, followed by the single most important behavioral note about partial updates, then a compact args list and a one-line return statement. Every line earns its place with zero 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?

Given the rich per-property schema, annotations, and output schema, the description covers the essentials: what it does, partial-update semantics, required event_id, parameter roles, and return format. It omits edge-case behavior such as error handling for an invalid event_id or permission requirements, which prevents a 5 but leaves nothing critical missing for a correct first call.

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

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

Despite the 0% coverage signal, the schema itself documents each property (e.g., 'New start datetime (ISO string)', 'New title (leave blank to keep existing)'). The description lists every parameter and groups title/start/end/description/location as 'Fields to update,' adding a bit of role clarity, but it provides no format or constraint details beyond what the schema already states.

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?

Opens with a specific verb and resource: 'Update one or more fields on an existing Google Calendar event.' The 'existing' qualifier and 'one or more fields' scope distinguish it from gcal_create_event, gcal_delete_event, and gcal_get_events without needing to inspect sibling schemas.

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: 'existing' plus the required event_id signal that this is for modifying an already-created event, not for creating one. However, no alternatives are named and no explicit when-not-to-use conditions are given, so the agent must infer the selection logic from sibling names.

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 (readOnly=false, idempotent=false), the description reveals the duplicate-prevention behavior around gcal_event_id and warns against reusing it for from-scratch creations. It also discloses the return shape. It does not discuss permissions or rate limits, but for a create operation this is solid behavioral context.

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

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

The description is front-loaded with purpose, followed by high-value usage conditions, then a compact parameter breakdown and return note. No sentence is redundant; the Args section earns its place given the low schema coverage signal.

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

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

The description covers creation scope, GCal sync behavior, recurrence, parameter semantics, and return value. It doesn't explicitly list which parameters are required, but the schema does; given the tool's complexity and available output schema, this is complete enough.

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

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

Although the context signal reports 0% schema coverage, the Args section enumerates every parameter with meaningful semantics: which fields are optional, which are for GCal sync, and what the recurrence types are. This fully compensates for the reported schema gap.

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

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

The opening sentence names a specific action ('Create') and resource ('Appointment in the Notion Appointments database'), immediately distinguishing it from siblings like notion_update_appointment or notion_get_appointments. The rest of the description reinforces this create-only scope.

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 explicitly contrasts the two creation contexts: syncing from Google Calendar (pass gcal_event_id) versus creating from scratch (omit it and call gcal_create_event separately). This directly tells an agent when to use this tool and when to delegate to a sibling.

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

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

The description communicates that the tool creates a task and returns a JSON dict with Notion ID and URL, which adds return-format context beyond the annotations. However, it does not mention behavior like repeated-call effects, permissions, or failure cases. There is no contradiction with 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 description is compact and front-loaded: one clear one-sentence purpose, followed by a terse Args list and a Returns note. There is no filler or redundancy.

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

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

For a simple create operation with a rich input schema and a stated return format, the description covers the essential inputs and output shape. The main gap is lack of explicit guidance on when to choose this over updating an existing task, but the low complexity makes this a minor omission.

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

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

The schema-level coverage is effectively 0%, but the Args block compensates by naming all three parameters (name, due_date, status) and their purpose, optionality, and default behavior. This is sufficient for an agent to populate the nested params object correctly, though it adds little beyond the schema's own property descriptions.

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?

Opens with a specific verb and resource: 'Create a new task in the Notion Tasks database.' This clearly distinguishes it from siblings like notion_update_task and notion_create_appointment. The return statement additionally clarifies what object is produced.

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 use for creating new tasks, but it does not explicitly state when to use this tool instead of notion_update_task or another sibling. A phrase like 'use notion_update_task to modify an existing task' would improve guidance. Sibling names make the distinction inferable but not 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 the tool as read-only and non-destructive. The description adds useful return behavior ('JSON dict of the appointment if found, or a not-found message') and the pre-sync duplicate-prevention role, which goes beyond the annotation hints.

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

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

The description is compact and front-loaded: purpose, use case, args, and returns each earn their place. There is no filler or redundancy beyond the reasonable Args/Returns documentation.

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

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

For a single-parameter read-only lookup with an output schema, the description fully covers what the tool does, when to use it, how to pass the parameter, and what to expect back. Nothing needed to call it 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?

The Args block documents the required params.gcal_event_id parameter and its search meaning, which compensates for the reported low schema-description coverage. It does not add format constraints or examples, but for a single plain string ID this is sufficient.

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 action and resource: 'Find a Notion appointment by its linked Google Calendar event ID.' The lookup key is explicit, making the tool clearly distinct from siblings like notion_get_appointments or notion_get_tasks.

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 explicit when-to-use guidance: 'Use this before syncing to check whether a calendar event already has a corresponding Notion record, preventing duplicate entries.' It does not name alternative siblings or state when not to use it, so it falls just 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 declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context by stating that results are returned as a JSON string and includes linked Google Calendar event IDs only when synced, which helps set expectations beyond the schema.

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

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

The description is concise, front-loaded with the core query behavior, and structured with clear Args/Returns sections. Some wording is redundant with the schema's property descriptions, but the overall structure remains efficient and scannable.

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 filtered query tool with annotations and an output schema, the description covers the essential aspects: what is queried, which filters exist, what fields are returned, and the return format. It does not mention sorting or pagination, but those are not critical for this simple query 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 description coverage is reported as 0%, so the description carries the burden of explaining parameters. The Args block successfully documents all four filters and their allowed values, adding practical meaning even though the schema itself also contains property descriptions.

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 verb and resource: 'Query the Notion Appointments database' with optional filters. It also enumerates the returned fields, making the tool's function concrete and distinguishable from sibling calendar/task 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?

The description gives clear context: use this to query appointments with optional date, type, and status filters. It does not explicitly mention when not to use it or point to alternatives like notion_get_appointment_by_gcal_id, but the filter-based framing is understandable enough for 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 establish that this is a safe read operation. The description adds meaningful behavioral detail by specifying the two inclusion paths (explicitly Overdue, or past due without Done/Archived/Overdue status) and the return shape as a JSON array. It goes beyond what annotations alone 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 description is concise and front-loaded: the first line states the action and resource, and the second defines the boundary conditions. Every sentence adds useful information with no filler or redundancy.

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

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

Given that the tool has no parameters, an output schema exists, and annotations cover the read-only behavior, the description is complete. It clearly defines the task selection criteria and the return format, so an agent can invoke it correctly without further clarification.

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

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

There are no parameters, and the schema is fully described with zero properties, so the description has no parameter burden. The baseline for zero-parameter tools is 4, and the description appropriately focuses on behavior and output instead of parameters.

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

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

The description clearly states the operation ('Return all overdue tasks') and the exact resource (overdue tasks in Notion). It also defines precisely what counts as overdue, which distinguishes it from a generic fetch like notion_get_tasks. The nuance about excluded statuses removes ambiguity.

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 the use case: retrieving overdue tasks rather than all tasks. However, it does not explicitly mention alternatives such as notion_get_tasks or give conditions for when to prefer this tool. The selection criteria are clear, but no explicit routing guidance is provided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds the output fields and filter semantics. However, it does not disclose pagination, ordering, or what happens when no filters are supplied. There is no contradiction with 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 description is compact and well-structured with Purpose, Args, and Returns sections. It front-loads the main query capability and avoids unnecessary filler, though the Args section partially duplicates schema information.

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

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

For a simple read-only query tool with an output schema and read-only annotations, the description covers the invocation, filter options, and returned fields well. Minor gaps such as pagination and ordering are not critical for first-time correct use.

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

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

The contextual signal reports 0% schema description coverage for the top-level params object, and the description compensates by documenting params.status, params.due_before, and params.due_after with allowed status values and date-filter behavior. This makes correct invocation clear even though the nested schema also contains some of the same details.

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

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

The description clearly states the verb and resource: 'Query the Notion Tasks database with optional filters', and it lists the returned fields. It does not explicitly differentiate this tool from the sibling notion_get_overdue_tasks, which overlaps when filtering by Overdue status.

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 when the agent needs Notion tasks with optional status/date filters and mentions Notion URLs for calendar linking, but it provides no explicit guidance about when to prefer this tool over alternatives like notion_get_overdue_tasks.

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=false, idempotent=true, destructive=false), and the description adds the key partial-update behavior ('Only provided fields change') and the return shape ('JSON dict of the updated appointment'). It does not address null-clearing semantics or external side effects, but the annotation coverage lowers the burden.

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

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

The description is compact and front-loaded: the first sentence carries the core purpose, followed by concise Args and Returns sections. Every line earns its place, with no redundant prose or repetition of schema contents.

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

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

Given a rich input schema, existing output schema, and annotations, the description provides the essential invocation context: the source of notion_id, partial-update semantics, and the return format. It is slightly thin on clearing-field behavior (null vs omitted), but this does not block correct use for the common update case.

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

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

The input schema provides detailed field descriptions for each updateable property, so the description does not need to repeat them. The description adds value by identifying the required notion_id source ('from notion_get_appointments') and by stating that any fields may be updated selectively, which clarifies the optional-parameter contract.

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—'Update fields on an existing Notion appointment'—with a clear resource and scope. 'Only provided fields change' differentiates it from create and get operations, and 'Notion' distinguishes it from Google Calendar 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?

Usage is implied rather than explicit: the description tells the agent to get notion_id from notion_get_appointments, which signals a prerequisite, but it does not state when to prefer this tool over notion_create_appointment, notion_update_task, or gcal_update_event. No when-not-to-use guidance is provided.

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

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

Beyond the annotations (not read-only, idempotent, non-destructive), the description discloses a key behavioral trait: updates are partial, not full overwrites. It also states the return type. It does not mention error behavior or permissions, but the annotations and schema already cover the safety profile.

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

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

The description is compact and logically arranged: purpose first, then argument list, then return value. Every sentence contributes useful information, and there is no redundant text.

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

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

The description, combined with the schema and annotations, gives an agent enough to invoke the tool correctly: what it does, which fields to update, how to obtain the ID, and what it returns. It does not explicitly address alternatives like notion_update_appointment, but the tool name and resource phrasing make the distinction clear.

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

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

The description names the updatable fields and adds the crucial source instruction 'from notion_get_tasks' for notion_id. The schema documents each parameter's meaning and allowed status values, so the description adds value without needing to repeat every detail.

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

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

The description clearly states the action ('Update fields on an existing Notion task') and the resource ('Notion task'), distinguishing it from the sibling appointment tools. The added sentence 'Only provided fields change' precisely defines the operation's scope.

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

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

The description gives clear usage context: use this to update an existing Notion task, and the notion_id should come from notion_get_tasks. It does not explicitly name alternatives or state when not to use this tool, but the resource type is unambiguous given the sibling set.

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 and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral detail beyond the annotations by specifying the three detection rules and thresholds: exact overlaps, fewer than 10 minutes between events, and events longer than 4 hours. It also states the return type as a JSON string, which is useful operational context.

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

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

The description is appropriately sized, front-loaded with the tool's purpose, and then provides the detection criteria, arguments, and return format in a clean structure. Each section earns its place; the threshold details and return summary are informative without being 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?

For a read-only conflict-detection tool, the description is complete: it states the exact purpose, the inputs, the detection rules, and the return format. The read-only annotations cover side-effect expectations, and the output schema is available, so the agent has enough information to invoke the tool correctly without additional inference.

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

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

The context signal reports 0% schema description coverage, so the description must compensate. The Args section explicitly maps all three parameters (start_date, end_date, calendar_id) to their meanings, adding semantic clarity beyond the bare params wrapper. While the schema already defines defaults and ISO formatting, the description's field breakdown helps an agent understand the role of each parameter.

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 starts with a specific verb and resource: 'Detect overlapping events or tight transitions in a date range.' It clearly differentiates this from sibling tools by naming the exact detection categories (overlaps, tight transitions, marathon sessions), so an agent can distinguish it from gcal_get_events or gcal_find_free_slots without opening schemas.

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 a clear context for when to use the tool: detecting conflicts or tight transitions in a calendar date range. It does not explicitly name alternatives or exclusion conditions, but the focused detection language makes the intended use obvious and distinct from listing events or finding free slots.

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 only declare readOnly=false, idempotent=false, destructive=false; the description adds the meaningful side-effect boundary that the Notion task is unchanged and only a calendar event with a visible pointer is created. It also states the return is a JSON confirmation, which is useful, though it does not mention duplicate-event or permission 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 description is well structured with a clear summary, workflow enum, Args list, and Returns note, and the most important behavioral warning is front-loaded near the top. It is slightly longer than strictly necessary because the Args section largely echoes the schema's own descriptions, but nothing is confusing or 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?

Given the output schema exists, the description still covers invocation sequence, parameter roles, side effects, and the return shape, which is sufficient for a single-purpose integration tool. It could be more complete by referencing an alternative for plain calendar events or mentioning calendar_id defaulting, but that is available in 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?

With the schema coverage reported at 0%, the Args section compensates by naming every parameter and its role (event title, embedded URL, ISO start/end, target calendar). It adds meaning by connecting task_name to the event title and task_url to the event description, and task_notion_id is clarified as the Notion page ID.

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: scheduling a focused Notion work block on Google Calendar. It then details the mechanics — event title from task name and Notion link in the description — and explicitly notes that the Notion task itself is NOT modified, which separates it from generic calendar-event and task-mutation 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 typical workflow places this tool in context after notion_get_tasks and gcal_find_free_slots, so an agent knows when in a sequence to invoke it. It does not explicitly state an alternative for generic calendar events or call out when not to use it, but the workflow and NOT-modified statement give clear usage context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description need not repeat safety. It does add value by disclosing that the tool aggregates three sources and returns a combined view, including an overdue_tasks key. It stops short of documenting edge behavior like timezone handling or how multi-day week boundaries are resolved, but for a read-only overview tool the disclosed behavior is adequate.

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 clearly organized sections: the one-line purpose, a plain-language explanation of the combined view, and a compact Args/Returns block. Every sentence earns its place, the most important info is front-loaded, and the return keys are listed explicitly.

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 aggregate tool with one straightforward parameter, an output schema present, and sibling names that clarify the alternatives, the description fully equips an agent to select and invoke it. The combined-source behavior plus the return-key list makes the tool's contract clear, and no mutation/prerequisite caveats are needed given the readOnlyHint.

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

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

Schema description coverage is 0% at the top level, but the nested 'date' property has its own description ('Any date within the desired week (ISO date string)'). The description text adds the key semantic that any date in the target week works and that it defaults to the current week, which matches and enriches the schema. Since there is only one parameter and the schema already explains it, the description's contribution is useful but not essential.

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 ('Get a unified overview') and resource ('a week') and describes exactly what it aggregates: calendar events, Notion appointments, and tasks due. It also names itself as the primary 'how does my week look?' tool, which distinguishes it from the individual sibling tools that fetch only one source.

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 explicitly frames this as the primary tool for a 'how does my week look?' query and explains that it pulls from all three sources, so an agent knows to use this instead of calling gcal_get_events, notion_get_appointments, and notion_get_tasks separately. It could be slightly more explicit about when NOT to use it (e.g., when only one event stream is needed), but the primacy claim is strong routing guidance.

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