Selvedge

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

Annotations already indicate safe read-only idempotent operation. The description adds value by detailing return fields (status, superseded_by) and error handling behavior (returns error object with isError: false). 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?

Two short paragraphs, no fluff. The first sentence immediately states the core purpose. Every sentence adds necessary 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?

Given a single parameter, existing output schema, and comprehensive annotations, the description covers the tool's functionality, return data, and error case fully and clearly.

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?

Only one parameter with 100% schema coverage. The description adds the constraint 'exact entity path (no prefix matching)' and provides examples, enhancing the schema's description.

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

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

The description clearly states the tool retrieves the most recent change to an entity, likening it to git blame for semantic entities. It distinguishes from siblings like history or diff by focusing on the latest change and including decision state.

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

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

The description explains what the tool does and notes error behavior when no history exists. It lacks explicit guidance on when not to use or alternatives, but the purpose is clear enough for correct selection.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds ordering (oldest first) and specific error format, going beyond annotations without contradiction.

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

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

Two sentences, each with clear purpose. No wasted words. First sentence states what the tool does, second gives usage context and error handling.

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 single-parameter tool with full schema coverage and an output schema, the description sufficiently covers ordering, error condition, and intended use. No gaps identified.

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

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

Schema description coverage is 100% and fully describes the changeset_id parameter. Description adds no new parameter semantics beyond what the schema provides, so baseline 3 applies.

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

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

Clearly states 'All events that share a changeset_id, oldest first.' It specifies the resource (events) and ordering, distinguishing it from siblings like 'history' (likely broader) and 'search' (different target).

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 'Use to reconstruct the full scope of a feature or task across multiple entities,' providing clear context. Also describes error behavior for empty changesets. Lacks explicit when-not or alternative comparisons.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context: newest-first ordering, dotted-prefix matching scope, and the derived `superseded_by` id with empty-string semantics for the latest event. 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 concise and front-loaded: the first sentence gives the core purpose, and the second provides high-value examples of prefix matching and derived data. Every sentence earns its place with no 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 and safety annotations, the description sufficiently covers the essential behavior: ordering, prefix semantics, and the derived superseded_by trail. It does not discuss sibling-tool selection, but the core functionality is thoroughly described.

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

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

The input schema covers both parameters fully (100% coverage), so the baseline is 3. The description restates prefix matching with an example but does not add new parameter-level semantics beyond what the schema already documents.

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 change history for a codebase entity, newest first, and highlights unique behaviors like prefix matching and the derived `superseded_by` field. However, it does not explicitly differentiate from the similarly-named sibling tool `history`, so it stops short of full sibling distinction.

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

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

The intended use is implied: call this when you need a chronological change history for an entity, especially with prefix matching. But the description does not compare this tool to alternatives like `history` or `blame`, nor does it mention exclusions or when not 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 readOnly=true, idempotent=true, and destructive=false, so safety is covered. The description goes beyond by disclosing the error behavior for unparseable 'since' input, returning a JSON error array instead of silently returning empty results. This is valuable behavioral context not in 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 two sentences: the first states purpose and ordering, the second gives usage guidance and error handling. It is front-loaded, with no wasted words, and every sentence contributes meaning.

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

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

Given the output schema exists and the description covers purpose, filtering, ordering, and error behavior, the tool is fully specified for an agent. The description is complete for this 5-parameter optional-input tool without needing to explain return values.

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

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

Schema coverage is 100% with detailed descriptions for each parameter, so the baseline is 3. The description adds minor value by explicitly stating these parameters can be combined, but it does not explain syntax or semantics beyond what the schema already provides. No compensation needed.

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

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

The description clearly states the tool's function: 'Filtered change history across all entities, newest first.' It uses a specific verb ('browse' implicitly via 'history') and resource ('all entities'), and the 'newest first' ordering adds precision. This distinguishes it from siblings like log_change, diff, and search.

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

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

The description gives explicit guidance on how to combine filter parameters ('since', 'entity_path', 'project', 'changeset_id') to scope results. It does not explicitly mention when not to use this tool or name alternatives, but the usage context is clear enough for an agent to know when to invoke it.

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

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

Annotations carry near-zero information (all false except openWorldHint), so the description carries the full burden. It comprehensively discloses: the warnings array on quality-validator failure, the exact error shape on validation failure, the dual-event rename behavior, supersede auto-linking, and append-only semantics. No contradiction with annotations (readOnlyHint=false correctly implies a write).

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?

Long, but every section earns its place given the complexity — headers ('Renames:', 'Rejections:', 'Superseding a reverted decision:') with code examples make it scannable. Slightly verbose in repeating rename semantics already in the schema's rename_from field, but organized enough that the density is justified.

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

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

Comprehensive for a 16-parameter write tool with 5 complex change_type workflows. The description covers all change types, the validation grammar, failure/error shapes, examples for each major flow, and the output schema exists. 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 coverage is 100%, giving a baseline of 3, but the description adds genuine orchestration semantics beyond the schema: rename's dual-event pattern (rename on old path + create on new path with metadata.renamed_from), the reject naming requirement ('name what was rejected AND what was chosen instead'), and that empty supersedes auto-links the most recent removal event. This is behavioral glue the schemas don't spell out.

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 — 'Record a change to a codebase entity' — and immediately distinguishes itself: call it after a meaningful change, while siblings diff/blame/history/prior_attempts are read surfaces. An agent can clearly separate it from the sibling 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?

Provides explicit when-to-use for each change_type: 'Call this immediately after making any meaningful change,' with dedicated workflows for rename, reject, revert, and supersede. Names why reject is preferable to re-deriving dead ends ('the next agent's prior_attempts query finds it as a high-confidence row') and why supersede beats editing history. 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?

Annotations already indicate read-only, idempotent, non-destructive behavior, and the description reinforces and expands this with 'Templated and deterministic — no LLM call; pull-only.' It discloses nuanced behaviors: conservative defaults, the meaning of outcome/confidence values, and that an empty list is the preferred normal answer. 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 long but information-dense, with a sensible structure: core purpose, usage timing, outcome semantics, and confidence policy. Every sentence carries meaningful guidance, though some sections could be tightened. The front-loading is effective; the most important instruction appears 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?

Given the tool's complexity, the description covers purpose, usage timing, result semantics, confidence filtering, recall widening, and edge cases like standalone rejections and reopen events. The output schema exists and the description also explains return fields thoroughly. Nothing critical is missing for an agent to select and invoke this tool correctly.

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

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

Schema coverage is 100%, so the schema itself documents all parameters. The description adds meaningful extra context, such as the default min_confidence behavior, how 'exact' rows clear the confidence floor, and the role of window_minutes as a tiebreaker for implicit removals. This goes beyond simple schema repetition, though it could have been slightly more parameter-by-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 clearly identifies the tool's purpose: retrieving prior change attempts on an entity with inferred outcomes. It states a specific action context ('Call this BEFORE editing an entity') and distinguishes the data it returns. However, it does not explicitly differentiate itself from siblings like 'history' or 'changeset', so an agent must infer which tool covers which kind of history.

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 when to use the tool: before editing an entity, to avoid repeating a rejected approach. It also explains how to widen recall via min_confidence. However, it does not say when NOT to use it or name any alternative tool, so the usage guidance is strong on 'when' but missing exclusions 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?

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds search semantics: full-text across four fields and substring matching with escaped wildcards (from schema). This contextualizes behavior beyond annotations, though pagination/ordering are not mentioned (but output schema covers returns).

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: one declarative purpose statement and one illustrative set of examples. No redundant content and the main intent is 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 search tool with two parameters, full schema coverage, output schema, and clear annotations, the description adequately conveys what it searches. The example questions help the agent map natural language to tool invocation; however, it does not mention result ordering or the limit parameter behavior (though schema covers limit).

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

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

Schema description coverage is 100%, including the case-insensitive substring behavior and wildcard escaping. The tool description adds only usage examples, not new parameter semantics, so it meets baseline but does not exceed schema detail.

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

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

The description uses the specific verb 'search' and names the exact resources (entity paths, diffs, reasoning, agents). Example queries like 'what changes were made for the billing feature?' clarify the scope and distinguish it from sibling tools like diff or blame.

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 example questions that signal appropriate use cases, such as cross-cutting search across multiple entities. It does not directly name alternatives or state when not to use this tool, but the examples imply broad search rather than targeted diffs or history queries.

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?

Even with annotations marking readOnly, deterministic, and non-destructive, the description adds substantial behavioral detail: no LLM call, no network, no automatic un-retiring, fallback to manual_review when dependency state is unobservable, and effects of later supersede events. This is far beyond what annotations alone convey.

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

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

The description is longer than average, but the tool has complex deterministic rules and edge cases that warrant the detail. It is front-loaded with the core purpose and organized by flag type, followed by output fields, ordering, and guarantees. The output field enumeration is slightly redundant with the existing output schema, preventing a 5.

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 this complexity, the description is complete: it explains all three surfacing mechanisms, non-obvious edge cases like manual_review, output shape, ordering, filtering, and determinism guarantees. Combined with the rich annotations and output schema, an agent has everything needed 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 100%, so the baseline of 3 applies. The description mentions filtering by entity_path, project, or agent, which reinforces the schema but does not add much new semantic depth. It does not describe parameter formats beyond what the schema already provides.

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

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

The description opens with a specific verb and resource: 'Decisions due for a revisit,' then enumerates the three deterministic rules and their resulting flags. It clearly distinguishes this tool from siblings by emphasizing it is surfacing-only, deterministic, and local-state-based.

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

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

The description gives clear context for when results surface: expiry-based, date-based, and condition-based rules, with explicit caveats like 'pure age alone never surfaces' and 'manual:LABEL never auto-fires.' It does not explicitly name sibling alternatives for exclusion, but the behavioral specificity makes intended usage unambiguous.

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