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

Annotations only say readOnlyHint=false and destructiveHint=false. The description adds critical behavior: it is mutating yet non-destructive, requires confirm='YES', renames specific files with a timestamped pattern, logs the rotation into the fresh log, and preserves forensic history. This is substantial context beyond structured fields.

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

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

Every sentence carries operative information: state mutation, safety, required confirmation, exact file paths and naming, self-logging behavior, and usage guidance. There is no filler, and the key safety and usage constraints are 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?

For a one-parameter mutation tool, this description is complete: it covers prerequisites, behavior, effect on files, safety, and when to choose alternatives. The output schema exists, so return-value detail is not required. Nothing needed to invoke the tool correctly is missing.

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

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

The schema only defines a 'confirm' string with an empty default and no description. The description fully compensates by stating that confirm must equal 'YES' and that anything else is refused, making the parameter's role and validation unambiguous.

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 action (rotates active audit logs) and a specific resource, explicitly contrasting with deletion. It is clearly distinguished from sibling tools like sassy_audit_log and sassy_audit_search by naming what it is not meant for.

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 says when to use it: 'Use when you want a fresh log tail while keeping history.' It also names the alternatives, sassy_audit_log and sassy_audit_search, and tells the agent to prefer them for reading. No usage ambiguity remains.

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 mark the tool as read-only, idempotent, and non-destructive, and the description reinforces that with 'Read-only.' It adds meaningful behavioral detail beyond the annotations: the exact log file path, truncation to 120 characters, newest-last ordering, row format, and the meaning of the two event types. This gives the agent a clear picture of what executing the tool will and won't do.

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 every sentence earns its place: purpose and format first, then parameter semantics, then explicit usage guidance and sibling routing. It front-loads the read-only nature and the core function before going into details, and avoids repetition of schema field names without adding context.

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?

This is a complete, self-sufficient description for a two-parameter read-only tool. It includes the data source, row format, ordering, truncation, defaults, event types, and explicit use cases. Since an output schema exists, the description need not detail return structure, and it still provides enough context 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 description coverage is 0%, but the description fully compensates for both parameters. It explains count as capping rows with a default of 20, and include_bypasses as controlling whether pattern_bypass entries are included, with defaults and the effect of setting it to False. This is exactly the semantic content the bare schema lacks.

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

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

The description states a specific verb and resource: it 'surfaces recent shell-interceptor pattern events from the local JSONL audit log' and even gives the file path. It clearly distinguishes itself from the sibling sassy_audit_log by saying 'For general log history use sassy_audit_log.' The purpose is further sharpened with the diagnostic use cases: explaining blocked commands and picking an allow_pattern label.

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 when to use the tool: 'Use it to diagnose why a sassy_shell command was blocked and to pick the exact allow_pattern label for a retry.' It also names the key alternative, sassy_audit_log, for general log history. Parameter guidance is embedded by explaining what include_bypasses=True vs False shows, so an agent knows how to configure the call for the two scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds specific behavioral context: log location (~/.sassymcp/audit.log), the record types, and the fact that arguments are sanitized/secret-redacted, plus the ordering and default count. This goes beyond annotations without contradicting them.

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

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

Two sentences, no filler. The read-only flag is front-loaded, followed by purpose, content, parameter behavior, and a sibling pointer. Every sentence earns its place.

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

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

For a single-parameter tool with an output schema, the description covers what it returns, how the parameter behaves, and the use case. Nothing essential is missing; an agent can call it correctly without further information.

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 has only 'count' with no description (coverage 0%). The description fully compensates by explaining that count sets the number of most recent lines returned, defaults to 50, and that output is newest last. This is essential 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?

The description clearly states the tool returns the tail of the audit log, specifies the content (timestamp, tool name, sanitized arguments, policy/interceptor events), and explicitly contrasts with sassy_audit_search. This distinguishes it from siblings without 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?

It explicitly states 'Use it to review what tools were called recently and with what arguments' and directs the agent to sassy_audit_search when searching for a term. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds behavioral detail beyond that: keyword matching is case-insensitive and line-based, results are newest last, count defaults to 50, and a no-match notice is returned. This gives a clear behavioral picture, though it doesn't mention edge cases like a missing log file.

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?

Four sentences, each earning its place. The description front-loads the read-only safety signal and core filtering behavior, then efficiently covers use cases, default behavior, and sibling differentiation without fluff.

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 two-parameter read-only tool with annotations and an output schema, the description is complete: it specifies the target file, matching semantics, ordering, default count, no-match behavior, and intended use cases. Nothing critical is missing for an agent to select and invoke it correctly.

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

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

Schema coverage is 0%, so the description carries the full burden. It compensates well: keyword is described as required and used for case-insensitive per-line matching, and count is described as limiting the result to up to count matching lines with default 50. This adds meaningful semantics beyond the bare schema fields, though it doesn't state any maximum or validation constraints.

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: it filters the audit log for a case-insensitive keyword match. It also names the log path, required keyword, and return behavior, making the tool's purpose unambiguous and distinct from siblings like sassy_audit_log and sassy_audit_false_positives.

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 guidance is explicit: use it to trace a specific command, pattern label, or tool name. It also names sibling alternatives with the conditions that select them ('unfiltered recent tail' → sassy_audit_log; 'structured interceptor block/bypass rows' → sassy_audit_false_positives), providing clear when-to-use and when-not-to-use 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 goes well beyond the annotations by detailing execution behavior: operations run through the normal tool call path, failures never raise, results return in request order with specific fields, and there are hard limits on operations and concurrency. It also acknowledges the tool can be either read-only or mutating, aligning with readOnlyHint=false and destructiveHint=true.

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 every sentence contributes: it covers dual-mode behavior, safety context, parameter semantics, error semantics, return format, and usage guidance. There is no filler or tautology, and critical warnings appear early.

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 provides enough detail for an agent to invoke the tool correctly: required operations structure, optional parameters with defaults, return value shape, and selection guidance. Even with an output schema present, describing the per-result fields adds completeness rather than redundancy.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it succeeds: it explains the operations array format and max 50 operations, max_concurrent range and default, timeout_seconds as a per-operation ceiling, and stop_on_error semantics. It even specifies that sassy_batch cannot be nested, which is critical for agents constructing valid parameter values.

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

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

The description identifies sassy_batch as a scheduling primitive for running multiple tool operations, clarifying that it can be read-only or mutating depending on the operations. It does not state a crisp one-line verb phrase like 'executes a batch of tool calls,' but the purpose is discernible from the explanation and usage guidance.

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: 'Use for independent fan-out; prefer stop_on_error for dependent pipelines and sequential calls when steps depend on prior results.' It also clarifies what the tool is not — a policy bypass — and explains that every operation runs through normal validation, audit, security, and rate limiting, which helps an agent decide when to use 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 indicate destructiveHint=true; the description adds that it is 'Mutating', performs a 'real mouse click', uses absolute coordinates across all monitors, and works cross-platform via pyautogui. This is meaningful context beyond the annotations, though it could have noted potential side effects like moving the cursor or focusing windows.

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?

Four sentences deliver the essential behavior, parameter semantics, coordinate caveat, prerequisite, and sibling alternatives with no wasted words. The opening 'Mutating' immediately signals the tool's nature.

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 simple schema, destructiveHint annotation, and presence of an output schema, the description fully covers what the tool does, how to use it correctly, and when to prefer alternatives. An agent can invoke it without external documentation.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains x/y as required absolute screen coordinates, button options ('left' default, also 'middle', 'right'), and clicks semantics (default 1, for double-clicks and beyond). All four parameters are meaningfully described.

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 ('performs a real mouse click on the host desktop') and explicitly contrasts with sassy_hotkey and sassy_type_text, so the agent can distinguish this tool from its siblings 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?

Provides explicit when-to-use ('Use it for clicking GUI elements'), identifies alternatives ('use sassy_hotkey for keyboard shortcuts and sassy_type_text for entering text'), and recommends a prerequisite call to sassy_screen_info or sassy_desktop_state for coordinates. This is complete 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, idempotentHint, and destructiveHint, and the description reinforces 'Read-only.' Beyond annotations, it discloses a concrete fallback behavior: if the registry cannot be read, it returns a note referencing SASSYMCP_LOAD_ALL / SASSYMCP_GROUPS instead of numbers. This is valuable non-obvious 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?

Every sentence in the description earns its place: what the tool does, what it reports, that it is parameterless, the fallback behavior, and when to use it. The structure front-loads the core purpose and the usage guidance comes at the end, making it 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 tool has no parameters and an output schema, so the description does not need to describe return structure. It covers the fallback case, expected output, and follow-up actions, making the description complete for safe and 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?

The tool has zero parameters and the schema already reflects that, so the description does not need much. However, it explicitly states 'Takes no parameters,' which removes any ambiguity and reinforces the empty input schema. This adds slight value beyond the schema, so a 4 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 a specific verb and resource: it 'estimates how much of the context window is consumed by currently registered MCP tool definitions.' It also specifies the output contents (total estimated tokens, percentage, heaviest tools, tool count, recommendations), making it easy to distinguish from sibling tools. It even names follow-up tools, reinforcing 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 provides explicit when-to-use guidance: 'Use this first when context feels low or before enabling heavy groups.' It also tells the agent what to do next—follow up with sassy_tool_groups and sassy_tool_group_toggle—so the agent knows the intended workflow and 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?

The description directly contradicts the idempotentHint annotation. It states 'refuses to overwrite an existing destination,' meaning a second call with the same destination would fail, making the operation non-idempotent. This is a clear contradiction to the annotation's idempotentHint: true. Because the description's behavior conflicts with the annotation, the transparency score is reduced to 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 detailed but not overly verbose. Every sentence contributes value: it states the copying behavior, metadata handling, directory recursion, parent directory creation, restrictions, overwrite refusal, and usage guidance. The opening 'Mutating:' is redundant with the annotations, but overall the structure is logical and information-dense. It earns a 4 for being comprehensive without excessive fluff.

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 essential aspects needed to call the tool: what it does, restrictions, overwrite behavior, and alternatives. Since an output schema exists, the description doesn't need to explain return values. It lacks explicit parameter definitions, but that is partially compensated by schema context. The main gap is the inconsistency with annotations, which affects trust but not completeness. It is nearly complete, so a 4 is appropriate.

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 has no descriptions for the 'source' and 'destination' parameters (0% coverage), so the description must compensate. It implies these parameters through context, such as 'duplicates a file or directory' and 'Parent directories of the destination are created as needed,' which gives some meaning. However, it never explicitly defines what each parameter represents, their formats, or constraints beyond inferable context. This is adequate but not fully explicit, hence a score of 3.

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

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

The description clearly states the tool's function: 'duplicates a file or an entire directory tree.' It specifies the verb (duplicate) and resource (file or directory), and distinguishes it from sassy_move by explicitly naming the alternative. This is unambiguous and allows an agent to understand exactly 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 usage guidance: 'Use it to duplicate files or trees; use sassy_move when you want to relocate rather than duplicate.' It also mentions using sassy_safe_delete if overwrite is needed. This clearly differentiates when to use this tool versus alternatives and gives practical advice for handling the no-overwrite constraint.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: platform-specific behavior (Windows pywinauto UIA backend, macOS System Events with Accessibility permission, Linux unsupported error), the include_taskbar default behavior, and the requirement for a GUI session. It doesn't describe the exact JSON return shape, but the output schema exists and the description says 'lean JSON'.

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-organized: it front-loads the core purpose, then covers the parameter, platform behavior, prerequisites, and usage context. Every sentence adds information. It's slightly long but each clause earns its place given the cross-platform complexity.

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

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

For a read-only list tool with one optional boolean parameter and an output schema, the description is nearly complete. It covers platform differences, prerequisites, and usage context. The only minor gap is that it doesn't explicitly state what happens on headless hosts beyond 'return an error' (which it does state), and it doesn't detail the exact JSON structure, but the output schema covers that.

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

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

Schema description coverage is 0%, so the description must compensate. It does: it explains the include_taskbar parameter's default (False) and its effect ('filtering out taskbar entries'). This adds meaning beyond the bare schema property definition. The description could have gone further with more detail on what 'taskbar entries' means, but it's sufficient for a single boolean 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 states a specific verb ('Lists') and resource ('visible open windows') with precise detail: title and absolute left/top/width/height coordinates spanning all monitors, returned as lean JSON. It clearly distinguishes itself from siblings like sassy_screen_info and sassy_click by describing its role in the UI automation workflow.

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 when to use it: 'Use it with sassy_screen_info to locate UI elements before sassy_click, or for a quick sense of what is open on the desktop.' It also provides platform-specific guidance (Windows vs macOS vs Linux) and prerequisites (GUI session, Accessibility permission on macOS), which helps an 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 annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses substantial behavior: UTF-8 decoding with replacement, error behavior for missing paths, default and effect of context_lines, response fields (identical, lines_added, lines_removed, truncated diff text), and the fact that metadata is ignored. This goes well beyond what the annotations alone 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 well-structured and front-loaded: read-only status and core action first, then encoding, errors, parameters, output, scope, and use case. Each sentence adds distinct information without redundancy, making it efficient for an agent to parse and act on.

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 an output schema and strong annotations, the description covers all essential operational aspects: inputs, defaults, error cases, output contents and truncation limit, scope limitations, and a recommended use case. An agent has everything it needs to select and invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must carry the parameter documentation burden. It clearly explains context_lines ('sets how many unchanged lines surround each hunk') and its default of 3. path_a and path_b are referred to as 'two files' and the encoding/error behavior adds useful meaning, though the description could more explicitly define their roles as source and target for diff direction.

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 'Compares two files and returns a unified diff,' a specific verb and resource that clearly identifies the tool's function. It further distinguishes itself from siblings like read_file or file_info by emphasizing content-only comparison and diff output, leaving no ambiguity about its 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 states a concrete use case: 'Use it to verify exactly what changed between two file versions before copying, restoring, or reviewing them.' It also clarifies that it compares file contents only and not metadata, which implicitly steers agents away from using it for metadata checks. However, it does not explicitly name alternative tools or state when not to use it, so the guidance is clear but not fully exhaustive.

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 goes far beyond the destructiveHint annotation by explaining the snapshot-to-staging recovery mechanism, path protections, multi-match refusal, fuzzy fallback with similarity threshold, UTF-8 handling, encoding/line-ending preservation, and returned preview. No contradiction exists between the description and 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 opens with the core action and mutation flag, then delivers dense but purposeful behavioral details. Every sentence adds necessary information about safety, matching, encoding, return value, or sibling routing; nothing feels redundant or decorative.

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 mutation tool with sparse schema descriptions and only destructiveHint in annotations, this description is complete: it covers safety/recoverability, failure modes, fallback behavior, encoding handling, output preview, and when to use an alternative. An agent has enough context to invoke it correctly and anticipate outcomes.

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 0% schema description coverage, the description compensates fully: old_text is the exact text to match, new_text is the replacement, and path refers to an existing file. It also explains the uniqueness requirement for old_text and the fuzzy-match behavior, adding important semantic detail not present in the schema.

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

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

The description states a specific action: replacing a single exact occurrence of old_text with new_text in an existing file. It clearly distinguishes this tool from sassy_edit_multi by explicitly positioning it for one surgical edit, and the uniqueness condition differentiates it from broader file-write 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?

It gives explicit usage guidance: use for one surgical edit and prefer sassy_edit_multi for batching several edits. It also states refusal conditions (protected paths, multiple exact matches, no exact match) and the fallback behavior, so an agent knows when the tool will not perform as expected.

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 flag destructiveHint=true and readOnlyHint=false, and the description adds valuable behavior beyond that: prior contents are snapshotted into a staging folder, any non-unique match aborts the entire call before writing, edits apply in order, protected paths are refused, and only a count of applied edits is returned. 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?

Every sentence earns its place: mutation warning, snapshot behavior, edits format and ordering, abort semantics, preconditions, return behavior, and sibling routing. The most safety-critical information is front-loaded with 'Mutating' and the all-or-nothing guarantee is stated early.

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 mutating two-parameter tool, the description covers format, ordering, atomicity, side effects, constraints, return value, and alternatives. With an output schema present and annotations supplied, nothing needed for correct invocation is missing.

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

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

Schema coverage is 0%, so the description carries the burden for parameters. It clearly defines edits as a JSON string array of {'old', 'new'} objects applied in order. The path parameter is only implied through 'the file must exist' and 'one existing file', but combined with the schema's required path string this is enough to use 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?

States a specific verb and resource: 'applies several surgical edits to one existing file in a single call'. It also explicitly distinguishes itself from the sibling sassy_edit_block, which is framed as the single-edit alternative. An agent can tell exactly what this tool does without opening any other definitions.

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 when-to-use guidance: 'Use it to batch multiple unique-match changes in one file; use sassy_edit_block when you want a single edit with a context preview.' It also states preconditions like 'The file must exist' and that protected paths are refused, which helps an agent avoid invalid 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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses critical behavior: it returns an error when the variable is unset and masks sensitive values based on the variable name, including the exact masking rule. This is rich behavioral context that 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 moderately detailed but every sentence earns its place: read-only note, core behavior, error case, masking rule, and sibling routing. It is front-loaded with the most important information and contains 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 one-parameter, read-only getter with an output schema and safety annotations, the description covers everything an agent needs: what it returns, when it errors, how masking works, and when to choose a sibling tool. 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?

With zero schema description coverage for the only parameter 'name', the description compensates fully by indicating that the parameter is an exact environment variable name. It also adds parameter-dependent semantics: whether the returned value is masked depends on substrings in the variable name.

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 value of one environment variable' from a specific process (SassyMCP server), giving a precise verb, resource, and scope. It also differentiates itself from sibling sassy_env_list by emphasizing it handles a single, known variable.

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 when to use this tool ('check a single variable') and when to use sassy_env_list instead ('browse the environment or do not know the exact name'). This gives an agent unambiguous 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, openWorldHint=false, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context beyond that: the output is sorted with a count, sensitive values are masked with a specific rule, non-sensitive values are truncated at 200 characters, and filtering is case-insensitive. This fully discloses behavior without contradicting 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?

Every sentence earns its place: read-only marker, output format, filter behavior, masking rule, truncation rule, and usage routing. The structure is logical and efficient with no redundant or filler 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?

Given a single optional parameter and an output schema (which handles return-shape documentation), the description covers all necessary call-time knowledge: what is listed, ordering, counting, masking, truncation, and how to use the filter. Nothing essential is missing for this tool's complexity.

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

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

Schema description coverage is 0%, so the description must carry the full burden for the filter_str parameter. It does so by specifying the type, default, and precise semantics: limits results to variable names containing the case-insensitive substring. This is complete and adds meaning the schema lacks.

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

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

States a specific verb ('Lists') and resource ('environment variables of the SassyMCP server process'), along with formatting details (sorted by name, with count). It explicitly differentiates from sibling tools by naming sassy_env_get and sassy_env_set as related but distinct actions, so an agent can tell them apart.

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?

Description explicitly says to use this tool to discover available variables before calling sassy_env_get, and directs that changes go through sassy_env_set. This provides clear when-to-use guidance and routes to the correct alternatives without requiring the agent to infer from names alone.

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

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

The description adds substantial behavioral context beyond the annotations: it is ephemeral ('lost when the server restarts'), scoped to the process only, returns 'the variable name, scope process, and an expiry note,' and explicitly disclaims system/user modification. These are non-obvious traits the agent could not infer from readOnlyHint=false or idempotentHint=true, and there is 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 the core mutating behavior, followed by scope, exclusions, return value, and usage guidance. Every sentence adds distinct information with no redundancy or filler, making it efficient and easy to parse.

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 two simple string parameters, an output schema, and annotations that already cover read-only/destructive/idempotent traits, the description supplies everything needed to invoke it correctly: what it does, its ephemeral scope, return value, and an explicit alternative. No critical information 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 0%, so the description must compensate. It frames the two parameters as a variable name and value within the server process scope, giving them meaning beyond the bare titles 'Name' and 'Value.' It stops short of describing edge cases like value formatting or validation, but the core semantics are clear.

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 'Mutating: changes the process environment of the running SassyMCP server' and states it 'Sets one variable immediately for the server process and anything it spawns from this point on.' This gives a specific verb, resource, and scope, and clearly distinguishes the tool from sassy_env_get/list and permanent-config tools by noting it does NOT touch system or user environment settings.

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

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

Explicit guidance is provided: 'Use it only for values needed during the current session; for permanent configuration change the OS or shell profile instead of calling this.' This states the when-to-use condition and names the concrete alternative, leaving no ambiguity about tool selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the core safety profile is covered. The description reinforces read-only behavior and adds useful state disclosure (e.g., Excel files handled via openpyxl, directory counts of immediate children). It doesn't disclose any hidden side effects or permissions, but given the strong annotation coverage, the added detail is sufficient.

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 slightly long but well-structured, front-loading the purpose and read-only nature, then detailing type-specific behaviors, and ending with usage guidance. Each sentence contributes unique information; no filler. It could be tightened (e.g., splitting into bullet points), but the density is appropriate for a tool with this much conditional output.

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 an output schema exists, the description need not enumerate return types, but it goes further by describing edge cases (Excel files, directory counts) and usage context. It covers when to use, what to expect, and routes to alternatives, making it complete for an agent to invoke correctly without further lookups.

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 has a single 'path' parameter with zero description coverage, so the description must compensate. It explains that 'path' refers to a file or directory path and details what metadata will be returned for that path, giving the parameter meaning beyond its bare type. It doesn't specify path format constraints (e.g., absolute vs relative), but it still adds substantial semantic value.

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 it is a read-only tool that returns JSON metadata for a path, enumerating the specific data (absolute path, type, size, timestamps, line counts, Excel sheet info, directory counts). It also explicitly distinguishes itself from sibling tools sassy_list_dir and sassy_read_file, so an agent can easily tell it apart.

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: 'Use it to inspect a path before reading or editing it', and names two alternatives with their distinct purposes (sassy_list_dir for browsing directory entries, sassy_read_file for contents). This leaves no ambiguity about when to select this tool over siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description reinforces this with "Read-only." It adds useful behavioral context by specifying that it returns a live snapshot including system, process, and audit-derived stats, which goes 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 detailed but well-organized with a colon-introduced list of returned fields. It is somewhat long, but every component—contents, no-params note, usage context, and preference guidance—serves a purpose.

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 configuration tool, the description covers what it returns, when to use it, why it is useful, and that no arguments are needed. The presence of an output schema further reduces the burden of describing return structure.

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 has zero parameters and 100% coverage, so there is little to add. The description still explicitly states "Takes no parameters," removing any ambiguity for the agent, which is appropriate at the baseline for a parameterless tool.

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 verb and resource: "Returns the full SassyMCP configuration plus a live system snapshot," then enumerates the contents in detail. It clearly differentiates from sibling sassy_set_config by framing this as the inspection counterpart.

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

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

Explicit guidance is given: "Use to inspect current server settings before calling sassy_set_config, or to diagnose performance and environment issues." It also advises "Prefer over guessing config values," which tells the agent when this tool is the right choice.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavioral detail: base64 decoding with UTF-8 replacement, the content field being replaced by decoded_content, GitHub token requirements, and default ref behavior. This is context beyond the structured fields and contains 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 description is front-loaded with the core action and then methodically adds auth, parameter semantics, decoding behavior, and sibling routing. Every sentence earns its place, with no filler or tautology.

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 file fetch, the description covers prerequisites (token), parameter semantics, behavior (decoding), and how it relates to sibling tools. An output schema is present, so return structure does not need restating. Nothing needed for correct invocation is missing.

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

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

Schema description coverage is 0%, so the description carries the full semantic burden. It explains required owner, repo, path (repo-relative), and optional ref with allowed values and default behavior, covering every parameter meaningfully.

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: 'Fetches one file from a repo and returns its contents plus SHA.' It also distinguishes itself from related tools by naming sassy_ghq_push as the paired write operation and sassy_gh_get_file_contents as the fuller alternative.

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

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

Provides explicit usage context: read a file before pushing an updated copy, use directory-path retrieval only when a raw directory listing is desired, and use a fuller variant for explicit tree traversal options. Names the exact alternatives and the conditions that select them.

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 mutation and non-idempotency. The description adds valuable context beyond annotations: it requires a GitHub token (GITHUB_TOKEN or GITHUB_PERSONAL_ACCESS_TOKEN) and returns the created issue as JSON. This is useful behavioral disclosure for a mutating tool, though it doesn't cover failure modes or rate limits.

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 organized: core behavior first, then required/optional parameters with an example, then token requirement, then routing to alternatives. Every sentence earns its place and no information is redundant with the schema.

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

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

For a 5-parameter create tool with an output schema, the description is complete: all parameters explained, defaults given, label encoding clarified, auth requirement stated, return value mentioned, and alternative tools named. An agent can call this tool correctly with the information provided.

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

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

Schema description coverage is 0%, so the description carries the full burden for parameter meaning. It explicitly identifies required owner/repo/title, documents body's empty-string default, and explains that labels is a comma-separated string converted to a label array with a concrete example. Every parameter is meaningfully covered.

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: 'creates a GitHub issue in the given repo'. It also differentiates itself from the sibling 'github_full sassy_gh_create_issue' by framing itself as the 'lean daily-driver create path'.

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

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

The description gives explicit routing guidance: use the github_full tool for assignees/milestones/other fields, use sassy_ghq_issues to find existing issues first, and use sassy_gh_add_issue_comment for comments. It also states required fields, leaving no ambiguity about when to invoke this 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description goes well beyond this by disclosing the pagination behavior (30 per page), the auth requirement (GITHUB_TOKEN or GITHUB_PERSONAL_ACCESS_TOKEN), and the significant gotcha that the GitHub issues endpoint includes pull requests in results. These are exactly the behavioral traits an agent needs to interpret results correctly.

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 ('Read-only. Lists issues in a repo, 30 per page.') and every subsequent sentence earns its place: parameter requirements, return format, the PR gotcha, auth, and alternative routing. It is on the longer side at eight sentences, but the density of non-redundant, decision-relevant information justifies the length.

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

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

The description covers purpose, all parameters, return format, auth prerequisites, a behavioral gotcha, and alternative tool routing. An output schema exists for return values, and annotations cover the safety profile. Nothing an agent needs to select and invoke this tool correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden for parameter semantics. It compensates well: it marks owner and repo as required, documents state's valid values (open default; closed or all), and explains page's default and 1-indexed convention. Owner and repo are self-evident from their names, so the description covers all non-obvious parameter behavior.

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: 'Lists issues in a repo, 30 per page.' It clearly states the read-only nature and distinguishes itself from siblings by naming sassy_ghq_issue (create) and sassy_gh_list_issues (full-featured alternative). An agent can immediately understand what this tool does and what it is not.

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

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

Explicit when-to-use guidance is provided: 'Use for a quick daily-driver listing; for label filters, sorting, direction, or custom page sizes use the github_full tool sassy_gh_list_issues. To create an issue use sassy_ghq_issue.' This names concrete alternatives and the exact conditions that select them, leaving nothing to inference.

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

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

Beyond the annotations, the description discloses that the tool is mutating, creates immediately, has no draft mode, returns the created PR as JSON, and requires a GitHub token. The annotations already mark readOnlyHint=false, and the description adds meaningful behavioral context that an agent needs before calling.

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, then covers required parameters, optional body, token requirement, immediate creation behavior, and alternatives in a compact, organized way. No sentence is wasted.

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

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

For a pull request creation tool, this description covers the action, required and optional parameters, output format, authentication, behavioral caveats, and when to choose sibling tools. With annotations and an output schema also present, the description is complete enough 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 description coverage is 0%, so the description must compensate. It does clarify head as 'source branch containing your commits,' base as 'target branch the PR merges into,' and body's default empty string. Owner, repo, and title are not elaborately described, but their standard meaning is reasonably inferable.

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: 'creates a pull request.' It also differentiates this tool from related alternatives like sassy_gh_create_pr and sassy_combo_pr_review, so an agent can clearly identify which tool is which.

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 states when to use this tool versus alternatives: 'The tool itself creates immediately with no draft mode; for draft PRs or more control use ... sassy_gh_create_pr' and 'To review an existing PR end-to-end ... use sassy_combo_pr_review.' It also lists required inputs and the token requirement, leaving little ambiguity.

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 mark the tool as mutating, non-destructive, and idempotent, and the description adds valuable context: it blocks force pushes and deletions, enforces rules on admins, sets no required status checks or reviews, returns JSON, and requires a GitHub token. No contradiction with annotations exists.

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

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

The description is front-loaded with the key action and preset details, then gives auth requirements and routing guidance. Every sentence adds necessary 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 the output schema exists, the return structure does not need to be re-explained. The description covers auth prerequisites, exact preset behavior, branch default, and alternatives, making it complete for correct invocation of this three-parameter 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 0%, so the description carries the parameter-semantics burden. It clarifies that branch defaults to main and references owner/repo context. Since owner and repo are conventional GitHub identifiers and the branch behavior is explicitly described, this is sufficient, though the description could be slightly more explicit about the expected forms of owner and repo.

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: it applies a fixed branch-protection preset to a branch in owner/repo. It further differentiates itself from sassy_gh_protect_branch, sassy_gh_get_branch_protection, and sassy_gh_remove_branch_protection by naming what this tool does and does not do.

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

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

Explicit routing guidance is present: use this for the quick standard lock-down of main, use sassy_gh_protect_branch for custom rules, and use the get/remove tools to inspect or remove protection. An agent knows exactly when to choose this tool versus 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 mark the tool as destructive and non-idempotent. The description adds context consistent with those hints: atomic commit, overwriting of file contents, error on malformed JSON, and the requirement of a GitHub token. This goes well beyond the annotation data and prepares the agent for side effects.

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?

Every sentence adds value: core purpose, required parameters, format notes, error behavior, overwrite warning, auth requirement, and an alternative tool. The description is front-loaded with the most important information and stays focused without verbosity.

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 mutating tool with no parameter descriptions and a destructive annotation, this description covers purpose, usage, side effects, authentication, and alternatives. The output schema exists to handle return values, so nothing critical 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 description coverage is 0%, so the description must explain all parameters. It does so comprehensively: branch must be the target branch name (with examples), message is the commit message, and files must be a JSON string array of {path, content} objects. This adds meaning the schema cannot convey.

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

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

The description clearly states a specific verb and resource: 'creates or updates multiple files in one atomic commit via the Git Data API'. It also explains the benefit of avoiding SHA/ETag problems, and explicitly differentiates from a single-file equivalent, making it easy for an agent to distinguish this tool from 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?

Explicit guidance is provided: when editing existing files, the agent should first get content with sassy_ghq_get; for single-file operations, branches, or repos, the tool sassy_gh_push_files is named as the fuller alternative. This gives clear when-to-use and when-not-to-use instructions.

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 goes well beyond the annotations by explaining that hooks can be stacked, that the hook list is in-memory, and what happens on both success and failure. It also tells the agent to read the returned playbook carefully. The only slight tension is 'appends' vs the idempotentHint, but stacking is described as possible rather than guaranteed, so no contradiction is evident.

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?

Every sentence adds value: the mutating effect is front-loaded, followed by the prerequisite, error behavior, success return, and when to use alternatives. It is detailed but not bloated, and no sentence is redundant with the schema or annotations.

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

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

For a one-parameter tool with an output schema, the description covers the essential context: what the hook is, how to find it, what to expect on failure, what is returned on success, and how to undo the action. Nothing needed for correct invocation is missing.

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

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

Schema coverage is 0%, but the description fully compensates: it defines hook_name as 'the exact hook ID,' describes lookup-failure behavior, and points to sassy_hooks_list for discovering valid names. This adds meaning well beyond the bare property name in the schema.

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

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

The description states a specific action and resource: it 'appends the named hook to the in-memory active hook list.' It also clarifies the mutating nature and distinguishes itself from related hook tools like sassy_hooks_list and sassy_hooks_deactivate, so an agent can tell it apart at a glance.

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 explicitly conditioned: 'Activate a hook when a task matches a known domain and you want structured expert guidance.' It also tells the agent to use sassy_hooks_list first and sassy_hooks_deactivate to unload, providing clear when-to-use and when-not-to-use 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 readOnlyHint=false and idempotentHint=true, and the description aligns with that. It adds valuable context beyond annotations: the session-scoped nature, the optional behavior (specific hook vs. clearing all), and the error case for non-active hooks. It does not over-explain but covers the key behavioral nuances.

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 the core purpose ('removes hooks'). Every sentence adds value: behavior, return formats, error case, and usage context. No fluff 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 tool with one optional parameter, the description covers all necessary context: what the tool does, when to use it, how to use it, expected returns, and error behavior. The presence of an output schema is not needed because return shapes are described explicitly.

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 has one optional parameter with no description (coverage 0%), but the description fully compensates. It explains that hook_name is optional, that passing a name deactivates that specific hook, and that omitting it clears all hooks. This is complete parameter documentation.

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 (removing hooks from the in-memory active list) and the resource (hooks). It distinguishes this tool from siblings like sassy_hooks_activate and sassy_hooks_list by naming the specific scope (session) and the contrast with listing active hooks.

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 explicit when-to-use guidance: when a playbook no longer applies or you want a clean slate before activating a different hook. It also names the alternative sassy_hooks_list for inspecting active hooks, providing a clear decision path for the agent.

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

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

Annotations already cover readOnly/idempotent/non-destructive safety, so the bar is lower. The description adds valuable behavioral context beyond annotations by stating it returns 'metadata only (no full instructions)' and includes a count plus names of currently active hooks. This clarifies a significant limitation an agent would otherwise discover only after calling the tool.

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 tightly-written sentences front-load the essential listing behavior, then state the lack of parameters, then give usage routing. Every sentence earns its place, with no filler or repeated annotation details beyond a single-word 'Read-only.'

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 listing tool with rich annotations and an output schema, the description is complete: it states scope, output composition, what is excluded, and how to route to alternatives. Nothing needed for correct invocation is missing.

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

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

The tool has zero parameters, for which the baseline is 4. The description redundantly states 'Takes no parameters,' which is already obvious from the empty schema but removes any ambiguity. No additional parameter semantics are 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 uses a specific verb 'Lists' with a precise resource ('every registered operational hook') and clearly defines the scope and output ('metadata only: name, owning module, one-line description, trigger phrases, count, active hooks'). This makes it immediately distinguishable from sibling tools like sassy_hooks_activate, sassy_hooks_suggest, and sassy_hooks_deactivate.

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

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

Explicit usage guidance is provided: use this tool to discover playbooks before calling sassy_hooks_activate, and use sassy_hooks_suggest instead when the request is known but the right hook is not. This names both when and when-not to use the tool, fully meeting the criterion.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds behavioral context: it returns ranked hooks, a top_match, and a hint, and specifies the empty-list behavior with a note to proceed without a playbook. This enriches what the annotations alone convey without contradicting them.

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

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

The description is compact and front-loads the read-only nature, then covers the core behavior, output, edge case, and usage guidance in three sentences. No filler; every sentence earns its place. Structure is logical 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 tool with one parameter, an output schema (implicitly providing return structure), and clear annotations, the description fully covers what an agent needs: input semantics, output composition, empty-result handling, and when to use it. The reference to the sibling activation tool ties it into the workflow. 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 0%, so the description must carry the burden for the single parameter. It explains user_text as 'the user's request in free text (required)' – sufficient to convey the meaning and that it's free-form. While it doesn't give format examples, the description compensates for the schema's lack of documentation.

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 (scores), resource (hooks), and outcome (returns ranked matching hooks, top_match, hint). It clearly distinguishes from sassy_hooks_activate by describing its role as a precursor. It also covers the empty-result edge case, 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?

Explicitly says when to use it: 'Use when you are unsure which hook applies or proactively when a request sounds like a known domain.' It then directs the agent to call sassy_hooks_activate with the top match, naming the next step. This is direct and actionable, with no inference needed.

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 proactively labels the tool as 'Mutating,' matching the destructiveHint annotation, and discloses that it sends a real keyboard shortcut via pyautogui. It adds important caveats beyond annotations: there is no output validation beyond a confirmation echo, so the agent should verify effects with sassy_screenshot.

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 the mutation warning, then follows a logical structure: purpose, key syntax, platform support, verification caveat, and sibling routing. Every sentence carries useful information and 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 single-parameter, mutating tool, this description is complete. It covers what the tool does, how to format the parameter, which platforms it supports, what the output reliability is, and when to use alternatives. The presence of an output schema means the return format does not need to be detailed in the description.

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 only provides a bare 'keys' string with no description, so the description fully compensates by explaining that keys are '+'-separated and by providing multiple valid examples. It also reveals the implementation detail that the string is split and passed to pyautogui, which helps the agent format the input 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?

States the exact action—'sends a real keyboard shortcut to the host'—and clarifies the resource being manipulated. Concrete examples like 'ctrl+c' and 'ctrl+shift+s' make the purpose unambiguous and distinguish it from sibling text and mouse 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?

Explicitly tells when to use this tool: 'Use it for shortcuts like save, copy, or window switching.' It also names the alternatives—sassy_type_text for typing text and sassy_click for mouse actions—and even recommends sassy_screenshot for verification when the effect matters.

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 (readOnlyHint=false, destructiveHint=true) are general, but the description adds crucial behavioral detail: method-specific safety, SSRF protection (private IPs, link-local, cloud metadata), redirect following, JSON parsing, and 10,000-character truncation. It also clarifies the exact mutation gate, exceeding what annotations convey. 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 description is dense but every sentence adds value: safety model, URL restrictions, parameter formats, response handling, and usage guidance. It is well-ordered, front-loads the mutation gate, and avoids redundancy despite its length.

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

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

Given the tool's complexity (multiple methods, security constraints, response parsing) and the existence of an output schema, the description covers all agent-relevant aspects: allowed methods, safety checks, parameter semantics, defaults, response structure, and usage routing. 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?

Schema description coverage is 0%, yet the description compensates fully by explaining every parameter: headers as JSON object string, body as UTF-8 string, timeout_seconds default 15, method default GET, allow_mutating default False, and url as the target. It adds formats, defaults, and behavior beyond the bare 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 clearly states the tool makes HTTP requests with read or mutate semantics depending on method, and explicitly distinguishes itself from web_inspector for deep page inspection. It names specific verbs (GET, HEAD, OPTIONS vs POST, PUT, PATCH, DELETE) and resource scope (HTTP/HTTPS URLs), leaving no ambiguity about 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?

Explicitly states when to use ('quick API calls') and when to prefer an alternative ('prefer web_inspector for deep page inspection'). Also provides conditional usage rules: mutating methods require allow_mutating=True, and only http/https URLs are allowed. No inference needed.

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 extensive behavioral details beyond the annotations: 5-second timeout per URL, redirect following, per-URL result structure (status code and ms), status values for blocked/error, and SSRF protections (private IPs, link-local, cloud metadata, non-http(s)). This far exceeds the readOnlyHint and idempotentHint already provided.

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 structured with the core purpose first, followed by technical details and usage guidance. Every sentence adds value—no filler—and it remains compact despite covering timeout, redirects, SSRF, and response format.

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 health-check tool, the description is comprehensive: it covers input format, behavioral constraints, error/block handling, and selection criteria versus the sibling. Combined with the readOnlyHint and idempotentHint, nothing an agent needs 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 schema only defines 'urls' as a string with no description (0% coverage). The description compensates by specifying that it is 'a single comma-separated string,' which is essential for correct invocation. This fully clarifies the parameter format.

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

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

The description clearly states the tool health-checks URLs with HEAD requests and reports status code and round-trip time. It explicitly distinguishes from the sibling sassy_http (which is for response bodies), making its purpose unambiguous and unique.

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 states when to use this tool ('quick up/down and latency checks') and when not to ('when you need the response body or anything beyond HEAD'), naming the alternative sassy_http. This provides clear 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?

Beyond the readOnly/idempotent annotations, the description discloses important behavioral quirks: dotfiles and common directories are skipped below the top level, per-level entry caps apply, depth is clamped, and warnings name how many items were hidden. This is exactly the kind of non-obvious behavior an agent needs to anticipate.

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 dense sentences with no filler. The most important information (read-only, listing behavior) is front-loaded, followed by non-obvious limits and sibling routing. Every clause earns its place.

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

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

For a two-parameter directory listing tool, the description covers ordering, recursion, hidden entries, caps, warnings, and usage guidance. The output schema already explains return shape, so no additional output documentation is needed. Nothing an agent needs to call this correctly is missing.

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

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

The schema has 0% description coverage, but the description compensates well for `depth` by explaining recursion, default value, and clamping to 1-10. The `path` parameter is not explicitly described, but its meaning is strongly implied by 'directory entries' and 'directory tree', so the slight gap is minor.

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 directory entries' and immediately specifies the exact resource and behavior: directory listing with [FILE]/[DIR] prefixes and sorted output. It clearly distinguishes itself from siblings by stating that metadata queries belong to sassy_file_info and content reads belong to sassy_read_file.

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 says 'Use it to explore a directory tree' and names the sibling tools for other needs, making the when-to-use and when-not-to-use boundary explicit. This is textbook-level 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, idempotentHint, and destructiveHint, but the description adds valuable context: it is a bulk loader, limits counts per section, and includes optional project filtering. It confirms the read-only nature and explains output structure, going beyond the bare 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 concise, front-loads the purpose and usage instruction, then details the output sections efficiently. Every sentence adds value, though it is slightly long due to enumerating sections, but that is essential for clarity.

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 single optional parameter, comprehensive annotations, and presence of an output schema, the description covers everything needed: when to call, what it returns, and alternatives. No critical information 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 has 0% description coverage, so the description must compensate. It explains the 'project' parameter as an optional substring filter that adds a project_memories section, providing critical meaning that the schema lacks. This fully clarifies the parameter's role.

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 loads a standard session-start context bundle in one call, specifies it is read-only, and enumerates the exact sections returned. It differentiates from siblings by naming sassy_memory_search and sassy_memory_recall as alternatives for different needs.

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 instructs to call at the START of every session, and provides clear when-not-to-use guidance by pointing to sassy_memory_search for targeted follow-ups and sassy_memory_recall for one exact record. This leaves no ambiguity about when to invoke this 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 declare destructiveHint=true and idempotentHint=false, and the description layers on substantial additional context: irreversibility ('no undo, trash, or recovery'), exact-match semantics, the forgotten:false error path when no record matches, and the exclusion of sassy_memory_log milestones. All statements are consistent 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?

Six sentences, each carrying a distinct fact: core action, match/irreversibility, return contract, usage condition, milestone exclusion, and handoff routing. It is front-loaded with the destructive action and contains 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?

For a one-parameter destructive delete with annotations and an output schema, nothing an agent needs to invoke it correctly is missing: purpose, safety profile, return semantics, exclusion of milestones, and the routing alternative are all present. No open questions remain.

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

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

Schema description coverage is 0%, so the description carries the full burden. It explains the single parameter meaningfully: 'key (required) must match exactly — only that one record is removed,' plus the no-match error behavior. The '(required)' hint slightly duplicates the schema's required array, but the exact-match and single-record semantics are genuine added value.

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 — 'permanently deletes the single memory record whose key exactly matches' — with precise single-record scope. This differentiates it from siblings like sassy_memory_search, sassy_memory_remember, and sassy_memory_log without opening any of their 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?

Gives an explicit when-to-use condition ('Use only when stored information is obsolete, wrong, or should not persist across sessions') and an explicit when-not-to-use with a named alternative ('Never use to clear state at session end — that is what sassy_memory_handoff is for'). Nothing is left to inference.

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

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

The description discloses the three side effects (upsert memory record, post to crosslink channel, log milestone), the overwrite behavior on repeat calls, the failure mode (crosslink_posted false, local-only handoff), and the exact memory key format. This goes well beyond the annotations, which only say readOnlyHint=false, openWorldHint=false, idempotentHint=false, destructiveHint=false. The description adds critical behavioral context about mutation and failure handling.

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-organized: it front-loads the mutating nature and the three writes, then details parameters, then behavior, then return value, then usage guidance. It is long but every sentence earns its place given the complexity of the tool. Slight deduction for density that could be split into clearer sections.

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 tool's purpose, parameters, side effects, return value, failure mode, and usage context. It even explains how the next session resumes. With an output schema present and this level of detail, nothing an agent needs 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?

Schema description coverage is 0%, so the description carries the full burden. It explains the required 'task' parameter, the status enum values, the comma-separated list format for several fields, the project scoping, and the context_notes purpose. It also explains how the task slug is derived (lowercased, spaces to underscores, first 40 chars), which is not 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 'Mutating: runs the session-end handoff protocol — three writes at once,' which states a specific verb, resource, and behavior. It clearly distinguishes this from memory tools like sassy_memory_remember and sassy_memory_forget by naming the handoff protocol and the three writes.

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 'Use at session end or when context runs low — not as a substitute for sassy_memory_remember.' This gives clear when-to-use and when-not-to-use guidance, and names the alternative tool. It also explains the next-session resume flow, which helps an agent decide 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?

Beyond annotations (readOnlyHint=false), the description discloses crucial behavioral constraints: the operation is append-only, entries cannot be edited or deleted, and the return value is {'logged', 'project'}. This gives the agent a clear model of side effects and persistence semantics.

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

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

The description is dense but every sentence serves a purpose: mutation flag, target table, parameter semantics, append-only constraint, return value, and usage alternatives. It is front-loaded with the most critical facts and contains 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?

With only 3 simple parameters and an output schema present, the description still goes beyond the minimum by covering mutation behavior, storage target, immutability, return shape, parameter details, and sibling routing. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 0%, but the description fully compensates: it explains event is a required free-text description with an example, and that project and tags are optional with tags being comma-separated. Every parameter is given semantic meaning beyond raw schema titles.

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 ('appends'), a specific resource ('milestones table'), and explicitly distinguishes it from the 'memories table'. It also names the intended use case ('significant completions, decisions, or changes'), leaving no ambiguity about 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?

Explicitly provides when-to-use guidance ('Use for significant completions, decisions, or changes worth a durable timeline') and names exact alternative tools for different scenarios (sassy_memory_remember for ongoing state, sassy_memory_milestones for reading history). This routes the agent to the correct sibling without extra inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds behavioral context beyond that: the hard cap of 100 on limit, the 'newest first' ordering, and the return format with specific fields. It also notes the data lives in a different table than search, which is useful operational context. No contradictions.

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 important fact ('Read-only') and packs each sentence with purpose. It covers behavior, parameters, return format, and usage in three sentences with zero fluff.

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

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

For a two-parameter, read-only tool with an output schema, the description covers all necessary aspects: what it does, how to filter and limit, the return structure, and when to use an alternative. Nothing essential is missing for an agent to invoke it correctly.

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

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

The schema provides only types and defaults with no descriptions (coverage 0%), so the description must fully compensate. It does: project is explained as an optional substring filter with default '', and limit is explained as controlling count of newest entries, with default 20 and a hard cap at 100. This adds significant meaning beyond the raw 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 ('reads back'), a specific resource ('milestone events written by sassy_memory_log'), and an ordering ('newest first'). It explicitly distinguishes from sassy_memory_search by noting they operate on different tables, so an agent can tell them apart 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?

It explicitly says 'Use to review the timeline of completions and decisions' and then gives the alternative: 'use sassy_memory_search to find arbitrary memory records, which live in a different table.' This provides clear when-to-use and when-not-to-use guidance, naming the sibling directly.

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 the access-counter bump as a side effect beyond the annotations (which only state readOnlyHint, idempotentHint, destructiveHint). It also clarifies the return structure and the 'found: false' error behavior, and states it does not search text. This adds meaningful context that the annotations do not cover.

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 fairly long but every sentence contributes value—core function, return shape, side effect, and usage alternatives are all covered. It is front-loaded with the primary purpose and the exact-match requirement, and it avoids filler. Slightly long for a single-parameter tool, but efficient in 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?

Given the tool's low complexity (one required parameter), the presence of an output schema, and annotations that cover safety, the description is exceptionally complete. It explains the exact-match requirement, the return fields, the side effect, and when to use alternatives, leaving no gap 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?

With schema description coverage at 0%, the description carries the full burden for the 'key' parameter. It explains that the key must match exactly and points to alternatives if the key is unknown. It does not specify format or length constraints, but the essential semantics are clearly conveyed.

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 ('fetches') and resource ('one memory record') with the exact matching criterion ('exact key match'), and explicitly distinguishes from the sibling sassy_memory_search by noting it does not search text. This leaves 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 guidance: 'if you do not know the key, use sassy_memory_search instead' and 'Use when you know precisely which record you need, e.g. a task state key from sassy_memory_handoff or sassy_memory_context.' It also names alternatives for keyword discovery and session-start bundles, covering when to use and when not to.

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 the full overwrite semantics, persistence across server restarts, refreshed updated_at field, priority behavior for session-start bundles, and the return shape. It enriches the idempotentHint with concrete upsert-idempotency details and does not contradict any annotation.

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

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

The description is information-dense but every sentence earns its place: mutation first, then upsert semantics, then parameter guidance, then return shape, then usage guidance. Key behavioral facts are front-loaded before parameter details.

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 tool's complexity normal for a persistent memory write, the description covers parameters, defaults, return values, persistence, naming conventions, and sibling alternatives. Nothing needed to call the tool correctly is missing.

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

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

With 0% schema description coverage, the description carries the full parameter burden and succeeds: it provides naming conventions for key, comma-separated format for tags, allowed values and default for priority, and scope semantics for project. This is far more useful than the bare 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 'Mutating: writes a persistent memory record' and then explains the upsert behavior, distinguishing it clearly from read/search/delete sibling memory tools. The verb is specific ('writes'/'upserts') and the resource is named ('persistent memory record, SQLite').

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 'Use whenever you learn something worth keeping across sessions' and names the alternative for cleanup: 'use sassy_memory_forget to remove a stale entry.' This gives the agent clear when-to-use and when-not-to-use guidance.

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