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

Beyond the annotations (readOnlyHint false, destructiveHint false), the description discloses critical side effects: the goal counts against the plan limit, exceeding it returns PLAN_LIMIT, an unknown category silently produces an uncategorized record, and targetHours is the only field in hours while everything else is minutes. This is rich, non-obvious behavioral context that an agent needs to avoid mistakes.

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

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

The description is a single dense paragraph that front-loads 'WRITES.' and the core purpose, then follows with critical usage notes. Every sentence adds value, though it could be structured as bullets for easier scanning. It avoids fluff while covering essential constraints.

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 7-parameter tool with no output schema, the description covers the major pitfalls: unit mismatch, plan limit, category validation, and user confirmation. It doesn't describe the response format, but that is largely inferable for a creation tool; the description provides enough to call successfully without hidden surprises.

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 100% schema coverage, the baseline is 3. The description adds meaningful extra semantics: category must be a value string, not a display name or id, and silently produces an uncategorized record if invalid; targetHours is explicitly the only field in hours (all others in minutes). These go beyond the schema's field descriptions, especially clarifying the unit convention.

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 verb 'creates' and the resource 'a new goal on the user's account,' distinguishing it from sibling tools like update_goal or create_task. It also reinforces the write nature with the leading 'WRITES.' token, leaving no ambiguity about what the tool does.

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 explicit preconditions: check the plan limit before calling (via get_context), confirm title/category/target with the user, and use get_context.categories[] values. It doesn't name alternative tools for other operations, but the creation-specific context and the warning against inventing goals from offhand remarks give clear practical 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 indicate a write (readOnlyHint=false) and non-destructive nature. The description adds the side-effect distinction that creating a task does not log time but completing it with update_task does, and that attaching a goalId affects report/progress meaning—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?

Three sentences, all purposeful, with the core action front-loaded. Minor redundancy with 'WRITES.' and the estimatedMinutes unit repeating the schema, but overall tight.

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 9-param create tool with a fully-covered schema, the description adds key behavioral context (no time logging, goalId preference) and references get_context for timezone/categories. It omits nothing critical an agent needs to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds the rationale for goalId ('makes reports and goal progress meaningful') and reiterates estimatedMinutes unit, but most parameter meaning is already in the schema. The added guidance nudges it to a 4.

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

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

The description clearly states the tool's action ('Creates a task') with optional attachments to a goal and schedule block, and explicitly contrasts it with goalslot_update_task for completion/time logging, distinguishing it from siblings like goalslot_create_goal.

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 explicit guidance: prefer attaching a goalId when the task serves one for meaningful reports, and clarifies this tool does not log time—use update_task for that. It names the alternative and the condition, satisfying the highest bar.

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 it read-only and non-destructive; the description adds that it is 'Cheap and side-effect free' and that it should be re-called after long conversations to avoid stale data. It also clarifies that the returned date and category values must not be guessed, providing additional behavioral nuance 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?

The description is front-loaded with the most critical instruction ('READ ONLY' and 'Call this first') and then provides a compact list of returned facts, followed by warnings. Each sentence contributes value, and the structure guides the agent clearly from invocation to handling of results.

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 there is no output schema, the description is the only source of return information, and it enumerates the key facts (user, plan limits, category values, timezone, date, week window, timer). It also covers the use-after-long-conversation nuance, making it fully sufficient for the agent to correctly invoke and interpret this tool.

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

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

The tool has zero parameters, so the description correctly says nothing about input semantics. The schema coverage is trivially 100%, and the description focuses on output context rather than inputs, which is appropriate for a parameterless tool. Baseline 4 is earned because there is no parameter documentation needed.

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

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

The description clearly states the tool's function: it retrieves the GoalSlot account context, enumerating the specific data it returns (signed-in user, plan limits, category values, timezone, etc.). It distinguishes itself from siblings by being the foundational context-gathering tool, and the imperative 'Call this first' reinforces its unique role.

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 instructs when to use it: 'Call this first, before any other GoalSlot tool, in every session' and 'Call it again after a long conversation rather than relying on a stale copy.' It also warns against assuming the date or inventing category values, clarifying that this tool is the authoritative source for those facts, leaving no ambiguity about when to invoke it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description reinforces this with 'READ ONLY' and adds useful behavioral context: it returns full detail and optionally includes the user's written reflections. It does not substantially describe output shape, 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?

Three short sentences, front-loaded with 'READ ONLY' and the primary purpose. The usage guidance and sibling alternative are compact and directly useful, with 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 simple single-goal retrieval tool with two well-documented parameters and strong annotations, this description covers what the tool does, when to use it, and how it differs from the closest alternative. 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?

Schema description coverage is 100%, so the schema carries the parameter documentation. The description adds no new parameter guidance beyond echoing the optional reflections behavior, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('get') and resource ('single goal'), and clarifies it returns 'full detail' with optional reflections. It also explicitly differentiates itself from list_goals, making its purpose unambiguous.

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

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

It gives an explicit usage condition: use when the conversation is about one specific goal. It also names the alternative (list_goals) and the condition for choosing it ('how are all my goals doing'), plus a rationale ('one request rather than many').

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 include readOnlyHint=true and destructiveHint=false, but the description adds meaningful behavioral information beyond that: results are merged by date, journal bodies are stored as HTML and converted to markdown, and there is a practical instruction to quote the user's words. This exceeds the baseline set by 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 front-loaded with 'READ ONLY' and each sentence earns its place: scope, content explanation, distinction from get_report, usage hint, and a formatting note. It is slightly long but not padded, and the structure is logical.

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 what data is returned, the merge behavior, the two data types, and the relationship to get_report. Without an output schema it does not spell out the exact response field structure, but the high-quality parameter schema and the description's detail make the tool adequately understandable for selection and 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?

The input schema has 100% description coverage for all five parameters, including formats, defaults, and timezone interpretation. The description adds no parameter-specific detail beyond clarifying the distinction between journal and check-ins, which is consistent with the schema's 'include' enum. The baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Returns') and resource ('the user's written journal and their daily check-ins') and clearly distinguishes itself from get_report. It is not a tautology and gives an agent enough to know exactly what this tool does.

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 contrasts with get_report ('as opposed to get_report which answers "where did my hours go"') and instructs when to use it ('Read both when the user asks how a week went'). This gives clear selection criteria against a sibling 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?

Beyond annotations (readOnlyHint=true, destructiveHint=false, openWorldHint=true), the description adds: response echoes the resolved date range, all durations are minutes, percentages are precomputed, and the tool normalizes answers. It also warns against inventing numbers, which is actionable behavioral guidance. 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 description is front-loaded with 'READ ONLY' and 'The single reporting tool', then systematically walks through every view, and ends with response-format guidance. Despite its length, every sentence provides unique value; there is no fluff. It is structured for quick scanning by an agent.

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 10 parameters, 9 views, no output schema, and rich behavioral expectations, the description covers everything an agent needs: view selection cues, date-range echo behavior, units, recomputation warnings, and explicit guidance on quoting ranges. It also clarifies edge cases like account-wide snapshots ignoring date ranges. Nothing critical 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 schema covers 100% of parameter descriptions, but the tool description adds significant meaning: it explains each view's use case, clarifies that groupBy applies only to summary, notes that presets are timezone-resolved, and highlights the schedule view's unique planned-vs-logged comparison. This goes well 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 states the tool is the 'single reporting tool' with a clear verb (get) and resource (report), and distinguishes it from siblings by noting it routes to the right report and normalizes the answer. It also lists all views with their purposes, making it unmistakable.

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

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

It explicitly explains when to use each view (e.g., 'day_total' for 'how did my week go', 'schedule' for planned vs logged) and instructs on how to quote the resolved date range to the user. It also says 'READ ONLY' and implies it is the go-to reporting tool, with no ambiguity about alternatives.

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 openWorldHint=true, but the description adds vital behavioral context by explaining that the schedule is a repeating weekly template, not dated events. It also specifies wall-clock times with no timezone and Sunday-first day indexing, which are not captured in annotations. This significantly enriches the agent's understanding beyond the structured metadata.

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 longer than average but every sentence carries essential information: the read-only nature, the repeating-template semantics, time and day conventions, and a clear usage directive. It is front-loaded with 'READ ONLY' and structured logically from purpose to usage, so the length is justified.

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 explains the return shape (grouped by day, sorted by start time) and the crucial conceptual distinction from a dated calendar, which is essential for an agent to interpret results correctly. It also clarifies the time format and day-of-week indexing, and provides explicit guidance to call this before proposing new blocks. With no output schema, this provides sufficient context for correct invocation and interpretation.

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 already fully describes the single parameter dayOfWeek with its range and Sunday-first indexing, achieving 100% coverage. The description repeats this convention but adds no new semantic meaning beyond reinforcing it, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns the user's weekly schedule template, grouped by day and sorted by start time. It explicitly contrasts it with a calendar of dated events, distinguishing it from sibling tools like goalslot_manage_schedule_block. The verb 'returns' and resource 'weekly schedule template' are specific and unambiguous.

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 says 'Call this before proposing any new block, so you can see which windows are already taken,' giving a concrete trigger. It also clarifies the repeating nature of the schedule, preventing the agent from misinterpreting it as a dated calendar. While it doesn't name alternatives, the instruction is clear and sufficient.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful context beyond that: the freshness of loggedHours tied to log_time, and a critical instruction to reuse returned ids verbatim in other calls. This is valuable behavioral disclosure not captured in 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 three sentences, each earning its place: purpose and output, usage context, and id-reuse guidance. It is front-loaded with 'READ ONLY' and avoids fluff, though 'READ ONLY' is slightly redundant given the readOnlyHint annotation. Still, it remains efficient and well-organized.

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?

Even without an output schema, the description explains what is returned (target hours, logged hours, progress, deadline), why ids matter (reuse in other tools), and how data stays current (tied to log_time). For a simple list tool with annotations covering safety, nothing essential 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% and every parameter (status, labelIds, categories, includeStats) already has an explanatory description. The tool description does not add any parameter-specific semantics, so the baseline score of 3 applies as the schema carries the full burden.

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?

Description states a precise verb and resource: 'Lists the user's goals with target hours, hours already logged, progress and deadline.' It also ties the tool to concrete user questions ('what am I working on' and 'am I behind'), making its purpose unmistakable and clearly distinct from siblings like list_tasks or get_goal.

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

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

Explicitly frames when the tool is appropriate ('This is the tool that answers...') and explains freshness behavior ('loggedHours is accumulated by time entries, so it moves whenever log_time is called'), which guides when to call it relative to log_time. It does not explicitly name alternatives or exclusions, but the context is clear enough for correct 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?

Beyond the readOnlyHint/openWorldHint annotations, it discloses result capping ('default 50'), the motivation ('a large backlog cannot flood the conversation'), truncation signaling, and the Sunday-first dayOfWeek convention that differs from weekly reports. These are non-obvious behaviors not visible in 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?

Two sentences, front-loaded with the read-only safety cue and a direct action, followed by the caveats that matter. There is 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 six-parameter list tool with no output schema, it covers the major invocation decisions: filters, statuses, cap/truncation, and date-ordering gotcha. It stops short of describing the response structure or sorting, but those are minor for correctly invoking the 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 schema already documents all six parameters with defaults, enums, and id provenance rules. The description adds useful context for limit and dayOfWeek, but mostly restates statuses and filters rather than introducing new parameter meaning, matching the baseline for high schema coverage.

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 'READ ONLY. Lists tasks' — a specific verb and resource — and enumerates the optional filters (status, goal, schedule block, day of week). This clearly separates the tool from siblings like list_goals or list_time_entries.

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 tool is for listing tasks and gives the filter dimensions and default cap, so an agent can infer when to call it. It does not explicitly name alternatives or exclusion conditions, but none of the sibling names compete for the same task-listing purpose.

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 readOnlyHint and destructiveHint, so the description's 'READ ONLY' adds nothing. However, it goes beyond the annotations by explaining the authoritative durationMinutes vs display-only durationHours distinction and the fact that the response echoes the resolved date range, which is critical behavioral context for correctly interpreting results. That extra value justifies a 4.

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 economical, with the key scoping guidance and alternative routing up front. The repeated 'READ ONLY' is redundant given annotations but harmless, and other sentences each add value: alternatives, duration handling, and range-echo caveat. No waste, though the redundancy keeps it from a perfect score.

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 there is no output schema, the description does well to explain the return shape (durations, total, echoed range) and the safety check about verifying the range. It covers the essential pitfalls an agent must know to use it correctly. The only minor gap is no mention of pagination or total semantics, but the limit parameter is self-explanatory and the tool is read-only, so completeness is strong.

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

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

Schema coverage is 100%, and each parameter (limit, goalId, preset, search, endDate, startDate) is already well-documented in the schema with defaults, formats, and timezone semantics. The description adds no parameter-specific information beyond what the schema provides, so the baseline of 3 applies. It does mention duration output but that is not parameter 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?

The description clearly states the tool returns 'the individual time entries the user logged over a window, with a total', specifying a distinct verb and resource. It further distinguishes itself from get_report by contrasting raw entries against aggregated rollups, making sibling differentiation explicit without needing to open 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 explicitly directs the agent to use get_report for aggregates, comparisons and per-goal rollups, and frames this tool as the raw-record alternative. The 'rather than summing these yourself' phrasing gives a clear when-to-use condition, and the absence of any other exclusions keeps the guidance unambiguous.

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 indicate readOnlyHint=false and destructiveHint=false, but the description goes further, disclosing side effects: 'When goalId is set this ALSO increases that goal's logged hours... wrong goalId quietly corrupts goal progress.' It also reveals free-plan per-day limits and the dryRun validation behavior. No contradiction with annotations; the description adds substantial behavioral context beyond the structured data.

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

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

The description is dense but well-structured, front-loading the purpose and then layering warnings and usage notes. It is perhaps longer than strictly necessary but every sentence adds critical operational detail (units, date sourcing, goal confirmation, dryRun). No filler; efficient for the complexity involved.

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 9 parameters and no output schema, the description covers all critical aspects: unit correctness, date handling, side effects, error prevention, and free-plan limits. It explains the dryRun mechanism for previewing batches. For a write tool, it anticipates the likely failure modes and equips the agent to handle them, making it complete for safe 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 adds value by giving concrete examples ('an hour and a half is 90') and explicit prohibitions ('Never send hours here and never send a decimal'). It also reinforces date sourcing from get_context.today and the goal side-effect warning. These enrich parameter understanding beyond the schema definitions.

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 'WRITES.' and states 'Records time the user already spent,' specifying the exact verb and resource. It positions itself as 'the workhorse tool for catching up on untracked work,' clearly distinguishing it from sibling tools like start_timer or list_time_entries. The purpose is unmistakable and specific.

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 explicit usage guidance: it is for recording already-spent time, warns 'Never invent a duration' and to ask if the user didn't specify length, and instructs to use 'dryRun true to show a batch to the user before committing it.' It also advises confirming goalId before logging to avoid corrupting progress. This goes beyond implied context to actionable do/don't 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?

The description discloses critical behaviors beyond the annotation flags: the template is repeating (every Tuesday), there is no single-date scheduling, conflicts reject with SCHEDULE_CONFLICT, dryRun writes nothing, and delete only removes one block. It also explicitly says 'WRITES' at the start, matching readOnlyHint=false without 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?

Though lengthy, every sentence is purposeful and action-oriented. It front-loads the most critical context ('WRITES' and the repeating template) and then systematically covers conflict, dryRun, plan limits, and delete semantics. No filler or repetition of schema 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?

For a complex mutation tool with 12 parameters and no output schema, this description covers all operational essentials: the template semantics, how to handle conflicts, how to validate with dryRun, the plan limit, and the delete/clear limitations. It references related tools (get_schedule, get_context) appropriately, leaving no gap an agent would need to guess.

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% with each parameter already described (e.g., required for create/update, formats, meanings). The description adds marginal parameter-specific detail, like the nuance of 'action delete removes a single block' and updateScope behavior, but the bulk of parameter meaning is already in the schema, so a baseline of 3 is appropriate.

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

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

The description clearly states the verb (create, update, delete), the resource (one block in the weekly schedule template), and the key distinguishing property: it operates on a repeating weekly template, not calendar dates. This alone separates it from any dated-event tool and matches its siblings like get_schedule.

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 explicit when-to-use and when-not-to-use guidance: use dryRun to validate a whole week before writing, re-read with get_schedule on conflict, stop one short of the plan limit, and never delete an incumbent block without asking. It also states that there is no way to clear the whole schedule, which prevents misuse.

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 annotations (readOnlyHint, destructiveHint), the description discloses several behavioral traits: notes form a tree and results carry full paths, HTML bodies are converted to markdown and truncated to maxChars, and omitting the query lists titles only. These details meaningfully explain what the agent can expect 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 description is compact and front-loaded with 'READ ONLY' and the primary purpose. Every sentence adds meaningful information: tree paths, HTML conversion, truncation, list behavior, and the explicit inability to mutate notes. 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?

Even with no output schema, the description explains what results look like (paths, converted markdown, truncated bodies, titles when no query). It also covers the key edge cases of empty queries and id-based fetching. Combined with the complete input schema and annotations, an agent has enough 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?

The schema already documents all five parameters (100% coverage), so a baseline of 3 applies. The description adds extra semantic value by explaining how the parameters interact: noteId fetches a single note, no query lists without bodies, and maxChars controls truncation. It also interprets the query as substring matching on title or body, which reinforces but slightly extends 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 verb and resource: finds notes by substring of title/body or fetches by id. It also clearly marks the operation as READ ONLY and distinguishes it from sibling tools by noting it cannot create, edit, delete, or share notes. This differentiates it from the many goal/task/schedule tools in the sibling 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?

Gives explicit usage context: use it to search/substring, fetch by id, or list without bodies when no query. It also tells the agent when not to use it by stating 'This server cannot create, edit, delete or share notes' and advises saying so rather than looking for another tool. This is clear guidance on both when and when-not.

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, the description discloses critical behavior: the timer is shared, only one can run, an already-running timer returns TIMER_ALREADY_RUNNING with details, and takeOver discards the running session with elapsed time lost and no time entry written. This gives the agent the safety-critical context needed for correct invocation. No contradiction with annotations; destructiveHint=false reflects the default non-destructive path.

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 action and uses a compact paragraph. It is somewhat dense, but each sentence adds necessary operational or safety information, so the length is justified.

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 there is no output schema and six optional parameters, the description covers the most important operational facts: single-timer constraint, conflict response, destructive takeOver semantics, and goal linking. It does not describe the success return payload, but this is a minor gap for a start action whose parameters are already well documented 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter guidance by warning that takeOver is destructive and by directing the agent to attach goalId when work belongs to a goal so stopping the timer credits that goal. This goes beyond the schema 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 states a specific action and resource: 'Starts the shared GoalSlot timer for this account.' It also clarifies this is the same timer seen in web/mobile apps, not a private one, and contrasts clearly with the sibling stop_timer tool by describing start behavior.

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

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

The description provides clear context: start the timer when work begins, and because only one timer can run at a time, do not use takeOver autonomously. It instructs the agent to surface the existing session and let the user choose to stop or replace it, effectively routing toward goalslot_stop_timer, though not by name.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses atomicity, goal crediting, the 1-minute floor and 12-hour cap with a 'capped' response marker, and that discard writes nothing and loses elapsed time. This is rich behavioral detail that the annotations do not provide.

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 'WRITES.' and the main action, then proceeds to edge cases in a logical order. While fairly dense, every sentence contributes essential behavioral or usage detail; there is no filler. It could be slightly tightened but remains efficient.

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 6-parameter tool with no output schema, the description covers the core behavior, edge cases, and usage guardrails. It does not mention what happens if no timer is running, which is a minor gap, but the critical operating details (floor, cap, discard semantics) are fully disclosed.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant meaning by stating that 'Attribution fields sent here override whatever the timer was started with,' clarifying the role of goalId, taskId, taskName, and scheduleBlockId. It also explains the discard parameter's effect beyond its schema description.

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

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

The description states the exact action: 'Stops the running timer and converts it into a time entry, or discards it.' It clearly identifies the resource (timer) and the two possible outcomes, and it distinguishes itself from sibling start_timer by being its inverse.

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 when a timer is running. It explicitly scopes the discard option with 'Only use it when the user says the timer was started by mistake.' It does not name alternatives like goalslot_log_time for manual entry, but the trigger condition is clear enough.

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 annotations (readOnlyHint false, idempotentHint true), the description discloses critical behavior: it writes, it cannot set loggedHours because those come from time entries, there is no archived status, and CLIs are needed for deletion. It also explains the partial-update expectation with 'Only send the fields that should change,' which is not derivable from the schema or annotations alone.

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 yet information-dense. Every sentence adds value: the opening line states purpose, then exclusions, status semantics, deletion guidance, and usage instruction. No filler or redundancy; it is well-structured with the core purpose front-loaded.

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?

Despite lacking an output schema, the description covers all operational aspects needed to invoke the tool correctly: what it updates, what it cannot update, how to handle related behaviors (logged hours, shelving, deletion), and the PATCH-like calling convention. The only minor gap is the return value, but the annotations and sibling context make this a complete picture for an agent.

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 fully describes each parameter. The description adds meaningful usage context by explaining that loggedHours is deliberately absent and instructs to send only changed fields, which clarifies partial-update semantics. This goes beyond what the schema states about optionality, though it doesn't add per-parameter 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 states exactly what the tool does: 'Updates fields on an existing goal, including its status.' This is a specific verb and resource that clearly separates it from sibling tools like create_goal or update_task. It also explicitly notes what it does not do (loggedHours, deleting), further sharpening purpose.

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 guidance on when not to use this tool and directs to alternatives: logged hours must be changed via log_time, and deletion is not available as a tool (tell the user to use the CLI). It also clarifies status semantics (no archived, PAUSED for shelving), which helps the agent decide when this tool is appropriate.

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

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

Beyond the readOnlyHint=false annotation, the description details side effects: completing a task creates a time entry, increases the linked goal's logged hours, and counts against the daily limit. It also warns against guessing actualMinutes, adding behavioral nuance the schema and annotations lack.

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 but information-dense, front-loading the write nature and then systematically covering each action's side effects. It avoids fluff, though the long run-on about complete could be slightly cleaned up; it's still effective.

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

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

For a tool with 13 parameters and three complex actions, it explains the core behaviors, side effects, and required conditions well. It doesn't cover failure states or edge cases like double-completing, but the essentials are all present, and the rich parameter descriptions fill gaps.

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 already covers 100% of parameters, but the description enriches key ones: actualMinutes is explicitly called out as required-for-complete and in whole minutes, date is clarified to default to today in user's timezone, and get_context.today guidance adds practical usage context 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 states a specific verb and resource, breaking down the tool's three actions (update, complete, restore) and their effects. It clearly distinguishes itself from related tools by positioning it as the single task-lifecycle manager, leaving no ambiguity about what it does.

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 clear context on when to use each action, such as using 'complete' rather than setting DONE so time is logged, and instructs to ask the user for actualMinutes. It doesn't explicitly name alternative tools like goalslot_log_time, but the self-contained lifecycle framing implicitly guides 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?

The description is rich in behavioral detail, but it directly contradicts the annotations: it warns that mode 'replace' REPLACES that day's whole journal body, while annotations declare destructiveHint=false. Additionally, 'append' mode is not idempotent, conflicting with idempotentHint=true. This is a clear annotation contradiction, so the score must be 1.

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 longer than typical but nearly every sentence earns its place by conveying a non-obvious constraint or warning. The 'WRITES.' opener is slightly redundant with 'Saves', but the information is front-loaded and well organized with an 'IMPORTANT' flag.

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 complexity of this write tool, the description covers the critical input semantics, mode selection, check-in validation, and tone guidance. The main gap is that no output schema exists and the description does not state what the tool returns on success or failure, leaving that to runtime 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?

Although schema coverage is 100%, the description adds substantial meaning beyond the schema: it explains the default replace behavior and when to append, warns that partial check-in fields are rejected, notes markdown conversion to HTML, and instructs the agent to write in the user's voice. This goes well beyond the parameter types and formats 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 opens with a clear action verb ('Saves') and names the resource ('user's journal entry and daily check-in for one date'). It also distinguishes this tool from read-only siblings like goalslot_get_journal by emphasizing the write/upsert behavior and the replace/append modes.

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 situational guidance: use 'append' when the day may already have content and the user did not ask to overwrite, and notes that partial check-in data will be rejected. It does not explicitly name alternative sibling tools, but the write-vs-read distinction and the append/replace rule provide strong usage direction.

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