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

With no annotations, the description carries the full burden. It usefully discloses the scan mechanism and exact socket paths, which is real behavioral context, and 'Discover' implies a read-only operation. However, it does not state the return format, whether stale sockets cause errors, or any permission requirements for scanning /var/run.

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 compact sentences with the discovery scope front-loaded and the technical mechanism immediately after. No filler or redundancy.

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

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

For a simple zero-parameter discovery tool with no output schema or annotations, the definition is nearly sufficient: it says what it finds and how. The only gap is that the shape of the returned instance list is not described, which would help an agent know what it can do with the results.

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 takes zero parameters, so there is nothing for the description to clarify; the baseline for a parameterless tool is 4. No parameter-related omissions exist.

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 ('Discover') and resource ('all running AimDB instances') and even names the mechanism (socket scanning). It is clearly distinguishable from data-oriented siblings like list_records or get_record, though it does not explicitly contrast itself with get_instance_info.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives such as get_instance_info. The usage context (discover before interacting with an instance) is only implied by the nature of the 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?

With no annotations, the description carries the full burden and does so well: it discloses that this is a destructive read whose values are consumed, the chronological ordering of results, and the non-obvious cold-start behavior where the first call creates a reader and returns empty. These are exactly the traits an agent would otherwise get wrong.

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

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

Front-loaded with the destructive semantics and ordered logically, but the 'since the last drain call' / 'since the previous drain' idea is stated twice, which is mild redundancy for a five-sentence description.

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

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

No output schema and no annotations, so the description must cover returns and side effects — it explains ordering, emptiness on cold start, and consumption. It stops short of describing the value payload shape or error/concurrency behavior, but it is adequate 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 100%, so limit, endpoint, and record_name are already documented in the schema. The description adds no syntax, format, or interaction detail beyond that, so the baseline of 3 applies.

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

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

States a specific verb (drain) and resource (pending values from a record) with explicit scope ('since the last drain call'). The destructive-read framing separates it cleanly from the read-only sibling get_record.

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

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

Gives a clear use case ('batch analysis of accumulated data — time-series analysis, trend detection'), which tells the agent when this tool is appropriate. It does not, however, explicitly name an alternative such as get_record or state when not to use 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?

With no annotations at all, the description carries the full disclosure burden. 'Return' implies a read-only, side-effect-free operation and it names the source file and the summarized fields, but it says nothing about permissions, mutation risk, or failure behavior when the state file is missing.

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, zero waste, and the most important content (what is returned and where from) is front-loaded before the usage cue. 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?

There is no output schema, so the description usefully compensates by naming the returned contents (record count, validation summary, decision log length). For a single-optional-parameter read tool this is largely sufficient; only error/absence handling is left unspecified.

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

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

Schema description coverage is 100% and the single parameter (state_path) is already documented in the schema, including its default. The description's mention of .aimdb/state.toml merely repeats that default, adding no syntax or format detail beyond the structured field.

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

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

States a specific verb+resource ('Return the current architecture state from .aimdb/state.toml as structured JSON') and even enumerates the payload contents. It is clearly distinguishable from mutating siblings like set_record or propose_* tools, though it does not explicitly separate itself from other read tools such as get_instance_info or list_records.

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 trigger condition: 'Run this first when entering an architecture session.' That is a concrete when-to-use cue. It stops short of stating when not to use it or naming an alternative tool, which keeps it out of 5 territory.

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?

No annotations are provided, so the description carries the full behavioral disclosure burden. It notes the instance must be running and that metrics are live, but does not state whether the operation is read-only, what permissions are needed, whether it has side effects, or how the returned metrics are shaped.

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

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

The description is a single, front-loaded sentence that states the action, resource, scope, and context without any 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 tool with no annotations and no output schema, the description is too thin. It does not explain what 'buffer metrics' includes, how the key substring matching behaves, or what an agent should expect back, leaving significant behavioral and output context unspecified.

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 both parameters are already documented in the schema. The description reinforces the role of record_key via 'matching a key string' but adds no syntax, format, or matching semantics beyond what the schema 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 states a specific verb ('Get'), resource ('buffer metrics'), and scope ('records matching a key string from a running AimDB instance'). It clearly distinguishes the tool from siblings like reset_buffer_metrics and get_record, though it does not explicitly name those alternatives.

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

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

The description implies usage context by requiring a key string and a running AimDB instance, but it offers no explicit when-to-use guidance, no exclusions, and no direct comparison to alternatives such as get_record or list_records.

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?

With no annotations at all, the description carries the full behavioral burden. It usefully discloses the return payload (version, protocol, permissions, capabilities), which is genuinely informative, but says nothing about whether this is a read-only/no-side-effect call, connection or auth requirements, or failure behavior when the endpoint is unreachable.

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 tight sentences with zero padding, front-loaded with the verb+resource and followed by the return enumeration, which earns its place since there is no output schema. "Detailed information" is mildly generic but is immediately cashed out by the field list.

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

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

For a simple single-optional-parameter read tool, the definition covers purpose, scope, and returned fields, and the schema fully documents the parameter including the env fallback. The only material gap is the absence of any statement about behavior when the endpoint is invalid or unreachable, which is a modest omission rather than a blocker.

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%: the single optional 'endpoint' parameter already documents accepted URL forms (unix://, serial://, bare path) and the AIMDB_CONNECT fallback in full detail. The description adds no syntax or format meaning beyond that, so the 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?

The description states a specific verb and resource ("Get detailed information about a specific AimDB instance") and enumerates the returned payload (version, protocol, permissions, capabilities). It is clearly distinguishable from read-only siblings like list_records or query_schema, though it never names discover_instances or any alternative by name, so sibling differentiation is implicit rather than explicit.

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

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

There is no when-to-use guidance, no prerequisites, and no named alternative. The phrase "a specific AimDB instance" only weakly implies this is for a known/connected instance rather than enumeration, leaving the agent to infer the boundary with discover_instances entirely on its own.

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?

With no annotations, the description carries the full burden. It discloses that the operation is a read and that the result is the record's current JSON value, which is useful. However it says nothing about what happens when the record does not exist, connection/auth requirements, or whether the value is a snapshot versus a live subscription.

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 sentences that are front-loaded with the action and immediately follow with the return value. 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?

The description compensates for the absent output schema by naming the return type (current JSON value). But for a tool with no annotations and no output schema, the absence of any error/not-found behavior keeps it only minimally adequate.

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 both parameters (endpoint with its env-var fallback, and record_name with an example) are already fully documented. The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get the current value of a specific record') plus the scope ('from an AimDB instance'), which clearly separates it from sibling set_record. It does not explicitly name a sibling to disambiguate against, but the read semantics are unambiguous.

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

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

There is no guidance on when to prefer this over list_records, drain_record, get_instance_info, or query_schema. The retrieval intent is implied by the verb, but no conditions or alternatives are stated.

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

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

With no annotations, the description carries the burden and discloses a genuinely non-obvious behavioral constraint: the instance must be built with the `profiling` feature, otherwise the call presumably fails. It also characterizes the payload (wall-clock timing per callback stage plus the slowest stage). It does not say what happens with no matching records or when the feature is absent, keeping it short of a 5.

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

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

Two sentences, front-loaded with the core action and return value, with the prerequisite placed last. The heavy parenthetical is dense but every clause adds information; 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?

No output schema exists, so the description must cover return content — and it does, naming per-stage wall-clock timings and the slowest stage. The feature-gate prerequisite is a key operational detail. It is close to complete, lacking only failure/empty-result behavior.

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 both `endpoint` (fallback to AIMDB_CONNECT) and `record_key` (substring match with example) are fully documented in the schema. The description adds no format or matching semantics beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb ('Get') and resource ('automatic stage profiling') with precise scope: per-`.source()`/`.tap()`/`.link()` callback wall-clock timing for records matching a key. The phrase 'from a running AimDB instance' and the returned 'bottleneck' value make it clearly distinguishable from siblings like reset_stage_profiling or get_buffer_metrics.

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

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

Provides a real precondition ('Requires the instance to be built with the `profiling` feature') and scopes usage to a running instance, which is useful context. However, it never says when to choose this over alternatives such as get_buffer_metrics or how it relates to the reset_stage_profiling sibling, so usage selection is only implied.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses semantics of the return content (directed edges, source→transform→consumer flow), implying a read-only operation, but omits permissions, pagination, or size/volume characteristics of the graph.

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

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

Front-loaded with the core action, and all three sentences are short. The second and third sentences partially overlap ('directed edges representing data flow' vs 'how data flows from sources through transforms to consumers'), so a little redundancy keeps it from 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?

With no output schema, the description adequately explains what the tool returns (directed edges and their data-flow meaning), which is the main thing an agent needs. It is slightly thin on how many edges or in what form, but complete enough for a simple read query.

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

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

Schema description coverage is 100%, and the single endpoint parameter is fully documented in the schema (unix/serial URL formats, env fallback). The description adds nothing beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('Get all edges in the dependency graph') and clarifies the resource is directed edges representing data flow. It naturally distinguishes itself from the sibling graph_nodes and graph_topo_order by dealing with edges, though it never names those siblings explicitly.

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

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

No when-to-use, when-not-to-use, or alternative guidance is given. With siblings like graph_nodes, graph_topo_order, and get_architecture in the same graph family, the agent gets no help deciding which to call for a given intent.

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?

No annotations are provided, so the description carries the full burden. It usefully discloses the shape of the return payload (origin categories, buffer configuration, connection counts) and implies a read-only operation, but says nothing about permissions, pagination, or the cost of enumerating all nodes.

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

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

Three short sentences, front-loaded with the core action and followed by return contents and purpose. No filler, though the third sentence is somewhat redundant with the second.

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 no output schema, the description does the work of summarizing the return shape, which is genuinely helpful. An agent has enough to invoke it correctly; only pagination/volume behavior is left unstated.

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

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

There is a single optional parameter at 100% schema coverage, whose description already documents the URL formats and the AIMDB_CONNECT fallback. The description adds nothing about the endpoint parameter, so the schema does all the work and 3 is the baseline.

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 ('Get all nodes in the dependency graph') and clarifies that 'nodes' means records with metadata. It is clear enough to distinguish from graph_edges and graph_topo_order by implication, but never names those siblings explicitly.

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

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

'Useful for understanding database topology and data flow' is a purpose statement, not a when-to-use rule. There is no guidance on when this should be preferred over graph_edges, list_records, or graph_topo_order, and no prerequisites or exclusions are given.

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?

No annotations are provided, so the description must carry the behavioral burden. It does disclose the operation is a read (Get/Returns) and describes the ordering guarantee, but it omits notable traits such as what happens when the graph contains a cycle (no valid topological order) and any auth or size/performance 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?

Three tight sentences, front-loaded with the core action and followed by the ordering guarantee and the ordering's provenance. 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?

No output schema exists, so the description correctly explains the return value (record keys in dependency order). It is largely self-sufficient for a read-only graph query, with the only gap being edge-case behavior such as cyclic graphs.

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 optional 'endpoint' parameter, and the schema already documents its format and env-var fallback at 100% coverage. The description adds no parameter semantics beyond the schema, so the baseline of 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?

Specific verb (Get) plus resource (topological ordering of records in the dependency graph), and it clarifies the semantics of the ordering ('all dependencies appear before their dependents'), which separates it from the sibling graph_nodes/graph_edges listing tools.

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

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

Usage is only implied: the description notes the result reflects AimDB's spawn/initialization order, which hints at when it is useful, but it names no alternative (e.g., graph_nodes) and gives no explicit when-to-use or when-not guidance.

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

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

With no annotations, the description carries the full behavioral burden. It helpfully discloses the return content (buffer type, capacity, producer/consumer counts, timestamps), but says nothing about pagination, permissions, or auth beyond the parameter's env-var fallback.

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 tight sentences with the core purpose front-loaded and no wasted words. Efficient, though the second sentence could be trimmed without loss.

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?

No output schema exists, so the description does need to describe return values, which it partially does. However, it omits list size, pagination, and ordering behavior, leaving meaningful gaps for a list tool.

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

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

Schema coverage is 100% and there is a single optional parameter, so the schema already documents 'endpoint' fully. The description adds no additional meaning beyond what the schema provides, making the 3 baseline correct.

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

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

States a specific verb and resource ('List all records') scoped to 'a specific AimDB instance', which an agent can distinguish from the single-record sibling get_record. It stops short of naming any sibling explicitly, so it earns a 4 rather than a 5.

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

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

There is no guidance on when to use this versus siblings like get_record, query_schema, or discover_instances, and no exclusions or prerequisites are stated. Usage is only implied by the verb 'List'.

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

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

With no annotations, the description carries the full load, and it does disclose the key non-obvious trait: this creates a proposal that must be shown to the user and is only committed via resolve_proposal. It stops short of describing what the call returns (no output schema, so a proposal handle/id is unexplained) or what happens on validation failure or duplicate names.

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 tight sentences with no filler: purpose, entity definition, and workflow constraint, in that order. The action is front-loaded and every sentence contributes information.

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

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

Covers the purpose and the two-phase proposal flow, which is the essential context. But with no annotations and no output schema, the description leaves the return value and the mechanics of the user-facing presentation unexplained, which matters for correctly chaining into resolve_proposal.

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 all four parameters are already documented in the schema, giving a baseline of 3. The description's mention that binaries 'group tasks' and 'optionally declare external broker connections' loosely maps to the tasks and external_connectors parameters and clarifies the latter's optionality, but adds no format or syntax detail beyond the schema.

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

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

States a specific verb and resource ('Propose adding a new binary definition') and then defines the domain entity: binaries are deployable crates that group tasks and may declare external broker connections. That definition cleanly separates it from siblings like propose_add_task or propose_add_connector, so an agent can pick the right tool without opening the schema.

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

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

Explicitly states the workflow obligation: present the proposal to the user before calling resolve_proposal, naming the follow-up tool. It does not, however, state when this tool should be chosen over the other propose_* siblings or what preconditions exist, so the routing guidance is contextual rather than 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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose the important human-in-the-loop trait (a proposal must be reviewed by the user before resolve_proposal), but says nothing about whether the proposal persists, what happens on rejection, or side effects on the target record.

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 sentences with zero redundancy; the action and its scope are front-loaded and the required follow-up call is appended where it belongs.

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 five fully documented required parameters, no output schema, and a proposal lifecycle referenced via resolve_proposal, the description covers what an agent needs to invoke it correctly. Minor gap: the fate of a proposal (approval/rejection/persistence) is left unstated.

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 every parameter (including the {variant} url template and the inbound/outbound enum) is already documented in the schema. The description adds no syntax, format, or constraint detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Propose adding a connector') plus concrete protocol examples (MQTT, KNX) and scopes it to 'an existing record'. It doesn't explicitly contrast with the nearby propose_add_record or propose_modify_* siblings, so it is clear but not fully sibling-differentiated.

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 prescribes the workflow step: present the proposal to the user before calling resolve_proposal. That gives real ordering guidance, but there are no when-not conditions or comparisons to alternative proposal tools.

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?

With no annotations, the description carries the full burden. It usefully discloses that this tool only proposes and that resolve_proposal is the follow-up, which tells the agent the call is non-committal. It does not say whether validation occurs, whether the payload is rejected on bad input, or what state the proposal is left in.

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

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

Three short sentences, front-loaded with the action, followed by the input reassurance and the required follow-up step. Nothing is padded or redundant.

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 10-parameter tool with a fully documented schema and no output schema, the description covers the essential process contract. The one gap is that it never explains how the resulting proposal is identified or handed to resolve_proposal, which an agent needs to chain the two calls.

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 enum explanations for buffer and nested field/connector objects, so the schema does the heavy lifting. The description's claim that 'all payload fields are explicit and typed' adds reassurance but no syntax or conditional detail (e.g., capacity only for SpmcRing) beyond what the schema already states.

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

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

States a specific verb and resource: proposing (not applying) a new record to the architecture. This distinguishes it from the other propose_* siblings (connector, task, binary) and from mutating tools like set_record, though it never names those alternatives explicitly.

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

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

The description gives one concrete workflow instruction — 'Present the proposal to the user before calling resolve_proposal' — which implies this is the first step of a two-phase flow. It does not say when to choose propose_add_record over set_record, rename_record, or resolve_proposal, so usage is implied rather than stated.

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

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

With no annotations, the description carries the full burden. It usefully discloses the two-phase proposal lifecycle (propose then resolve_proposal after user presentation), but omits whether the proposal requires approval, what happens on rejection, or whether it persists — significant gaps for a mutation-adjacent 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 short sentences with zero waste; the core action is front-loaded and the sequencing constraint follows logically.

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 proposal-creation tool with no output schema, the description adequately conveys the task concept and the propose/resolve lifecycle. It could go further on what the proposal needs to be actionable, but nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents name, inputs, outputs, task_type, and description. The description adds conceptual framing (what tasks do) but no parameter-level meaning beyond the enum already explained in the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('Propose adding a new task definition') and defines what a task is ('async functions that produce, transform, or consume record data'), which cleanly separates it from sibling propose_add_record/propose_add_connector/propose_add_binary 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 workflow sequencing ('Present the proposal to the user before calling resolve_proposal') which implies usage, but never states when to choose this tool over the many sibling propose_* variants or what prerequisites exist for adding a task.

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?

No annotations are provided, so the description carries the full burden. It usefully discloses that this defers the change (proposal, not immediate mutation) and requires resolve_proposal to take effect. It omits what happens on rejection, whether the change is validated against the record's existence, and any error behavior.

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

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

Two sentences, front-loaded with the action and immediately followed by the critical workflow constraint. 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 proposal tool with no annotations and no output schema, the description covers purpose and the required follow-up step. It is nearly complete; only error/validation behavior and what the proposal yields are left implicit.

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

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

Schema coverage is 100%, so every parameter is already documented including the SpmcRing/capacity conditional. The description only restates the buffer/capacity pairing without adding format or edge-case meaning. Baseline 3 applies.

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

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

States a specific verb+resource: proposing a change to a record's buffer type (and optionally capacity). It is distinguishable from propose_modify_fields and propose_modify_key_variants by its buffer-specific scope, though it never names those siblings explicitly.

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

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

Gives clear operational context — 'Present the proposal to the user before calling resolve_proposal' establishes the two-step propose/approve workflow. It does not, however, state when to choose this over the other propose_modify_* 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?

With no annotations, the description carries the full burden and does disclose a critical behavioral trait: this replaces ALL fields, so unchanged fields must be re-included. It also reveals the two-phase propose-then-resolve flow, though it omits permission, reversibility, and failure behavior.

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

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

Three tight sentences, fully front-loaded: the core action first, then the critical replace-all caveat, then the workflow step. 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 no-output-schema proposal tool with a rich input schema, the description covers the action, the replace-all semantics, and the resolve step. It could clarify that nothing is applied until resolve_proposal succeeds, but it is largely complete.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema by clarifying that 'fields' is a complete replacement list requiring unchanged fields to be included.

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

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

States a specific verb+resource: proposing replacement of the value struct fields of an existing record, which clearly separates it from propose_add_record and propose_modify_buffer. It names the resolve_proposal follow-up, though it doesn't explicitly contrast with the other propose_modify_* siblings.

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

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

Usage is implied (modify existing records' fields) and a workflow hint is given (present to user before resolve_proposal), but there is no explicit when-to-use-vs-alternatives guidance or exclusion criteria against the other propose_* tools.

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?

With no annotations, the description carries full behavioral burden. It usefully discloses the two-phase proposal pattern (propose now, resolve later, present to user first), which is real context beyond the schema. However, it omits permissions, conflict/staleness behavior, and whether the proposal is persisted.

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 with the purpose front-loaded, followed by usage and the follow-up action. Parenthetical examples earn their place; nothing is padded.

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

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

For a proposal tool with no output schema and no annotations, the description covers the essential workflow: purpose, trigger conditions, and the required follow-up (resolve_proposal). It is close to complete, missing only edge-case behavior such as conflicting or stale proposals.

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 all four parameters (including the optional key_prefix and the replacement semantics of key_variants) are already documented in the schema. The description's examples ('["Default"]') duplicate schema content and add no new parameter meaning.

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

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

States a specific verb+resource: proposing an update to the key variants of an existing record. It is distinguishable from siblings like propose_modify_fields or propose_modify_buffer by the 'key variants' resource, though it never explicitly contrasts with them.

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

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

Gives concrete when-to-use conditions ('adding a record with no variants' or 'expanding a fleet') and routes the agent to the next step ('present to the user before calling resolve_proposal'). It lacks explicit when-not-to-use guidance (e.g. versus propose_add_record).

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?

With zero annotation coverage the description carries the full burden, and it discloses the non-obvious inference mechanism ('inferred from current value + database metadata') plus ambiguity-handling guidance ('ask the user for clarification'). It omits explicit read-only/safety framing and error behavior for unknown records, but the added behavioral context goes beyond what 'Get' alone conveys.

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

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

Front-loaded with purpose and return shape, then use-case, then inference note, then a tip. Every sentence carries information, though the semantic-naming tip is marginally advisory rather than essential.

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?

There is no output schema, so the description must characterize the return, which it does at a high level ('data structure, field types, and metadata'). Combined with a 100%-covered input schema and the inference note, an agent has enough to call it correctly, though return-format specifics are unstated.

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

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

Schema description coverage is 100%, so the schema already documents endpoint, record_name, and include_example, including the env-var fallback. The description adds no parameter-level detail, so the baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Get JSON schema and type information for a record') and clarifies the output ('data structure, field types, and metadata'), which is clearly distinct from the value-fetching sibling get_record. It stops short of naming a sibling explicitly, so the differentiation is implied rather than stated.

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

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

'Use this before setting record values to understand expected format' gives a concrete when-to-use trigger tied to set_record. There is no when-not guidance or named alternative, but the context is clear enough for an agent to place it in a workflow.

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?

With no annotations, the description carries the full burden and does well at disclosing the non-obvious behavior: the action is deferred (pending proposal) and the blast radius is narrow ("Task definitions are preserved; only the binary grouping is removed"). It still omits permission requirements and error behavior for a nonexistent binary_name.

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

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

Three short sentences, front-loaded with the action and the confirmation requirement, and the scope caveat last. No filler or redundancy.

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

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

For a single-parameter proposal tool with no output schema and no annotations, the description covers the essential facts: it is a proposal, how to confirm it, and what is preserved. Only secondary details such as failure modes and permission requirements are absent.

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 and schema coverage is 100%, with the schema describing binary_name as "Name of the binary crate to remove." The description adds nothing beyond the schema about the identifier's format or resolution rules, so the baseline of 3 applies.

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

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

States a specific verb and resource ("Propose removal of an existing binary") and immediately clarifies that this is a staged operation rather than an immediate delete, which distinguishes it from siblings like remove_task and remove_record. An agent can identify it without opening the schema.

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

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

Explicitly routes the agent to the required follow-up: "Creates a pending proposal — call resolve_proposal to confirm." That gives clear context and a named alternative for the confirm step, though it does not state when this tool should be preferred over other removal paths or list prerequisites.

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?

With no annotations, the description carries the full burden, and it does real work: it discloses that the call is non-destructive on its own (creates a pending proposal requiring resolve_proposal) and warns of a cascading side effect ('removing a record breaks generated type aliases'). It omits whether the record must already exist and what happens to dependent buffers/connectors.

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 sentences, front-loaded with the core action, then the required follow-up, then the risk note. No filler and every clause carries information.

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

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

For a one-parameter tool with no output schema, the description covers the essential non-obvious facts: the two-step confirm workflow and the type-alias side effect. Only minor gaps remain (preconditions on record existence, effect on dependent artifacts).

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% — the single parameter is fully documented in the schema (PascalCase name). The description adds no syntax or format guidance beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource ('Propose removal of an existing record') and immediately clarifies that this is not an immediate mutation but a pending proposal. This distinguishes it cleanly from immediate-effect siblings like remove_task/remove_binary and from mutating siblings like set_record/rename_record.

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

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

Gives concrete follow-up guidance ('call resolve_proposal to confirm'), which is the key usage step in a two-phase workflow. It does not, however, state when NOT to use it (e.g., versus set_record with empty config, or how it differs from rename_record), so it stops short of full routing guidance.

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

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

With no annotations, the description carries the full behavioral burden and does well by disclosing that removal is a two-step proposal/confirmation process. It also warns that removing a task affects binaries that reference it. It does not cover permissions, reversibility, or rate limits, but the key non-obvious behavior is exposed.

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

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

The description is three short sentences with no wasted words. It front-loads the main action, then the required confirmation step, then the side-effect warning in a logical order.

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 proposal mutation with full schema coverage and no output schema, the description supplies the essential workflow and side-effect context. It is nearly complete, though it could add a note about where task names come from or whether the proposal can be rejected.

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 sole parameter task_name is fully documented in the schema as the snake_case name of the task to remove. The description adds no additional parameter semantics beyond what the schema already provides, making 3 the appropriate baseline.

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: proposing removal of an existing task. It distinguishes the tool from direct removal tools by clarifying that it creates a pending proposal, and it names resolve_proposal as the confirmation step.

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 clearly indicates the usage context: propose removal here, then call resolve_proposal to confirm. It does not explicitly say when not to use this versus siblings like remove_binary or remove_record, but the workflow and the affected resource are made clear.

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

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

With no annotations, the description carries full behavioral burden and does meaningful work: it discloses that the operation is a non-committal proposal requiring a separate confirmation, and warns that it renames the generated key enum and value struct, breaking existing references. It omits permission requirements and reversibility of the proposal, minor gaps.

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 tight sentences, front-loaded with the action and the required follow-up, ending with the critical side-effect warning. Every sentence earns its place with no filler.

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

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

For a two-parameter mutation with no output schema, the description covers the mechanics (proposal flow) and the key risk (broken references). It could note whether the pending proposal can be inspected or cancelled, but nothing essential to 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 100%, and both parameters ('old_name' as current PascalCase name, 'new_name' as new PascalCase name) are already fully documented in the schema. The description adds no parameter detail beyond that, so the baseline of 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?

The description states a specific verb and resource ('Propose renaming a record') and immediately clarifies that it does not rename directly but creates a pending proposal. This distinguishes it from the destructive 'remove_record' and the direct 'set_record', though it doesn't explicitly name a sibling it is meant to be preferred over.

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 the clear two-step workflow: propose here, then 'call resolve_proposal to confirm'. That is actionable routing guidance. It stops short of stating when to use this over siblings like 'set_record', so it lacks explicit exclusions.

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

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

With no annotations, the description carries the full behavioral burden and does disclose two real prerequisites (write permission and the `metrics` feature flag) plus the scope (all records, running instance). It does not explicitly warn that the current counter values are irreversibly lost or state the response, but for a reset tool the prerequisites and scope are meaningful disclosures beyond the schema.

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

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

A single front-loaded sentence with the action and scope first and the prerequisites tucked into a parenthetical. Zero wasted words.

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?

No output schema or annotations exist, so the description must stand alone; it covers purpose, scope, and prerequisites adequately for a reset operation. It leaves minor gaps around the result of the reset and confirmation of irreversibility, but nothing essential to calling 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 100% and the single endpoint parameter is fully documented in the schema (formats, AIMDB_CONNECT fallback). The description adds no meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (reset) and resource (buffer introspection counters produced/consumed/dropped/occupancy) with the scope 'for every record on a running AimDB instance'. This is clearly distinct from the read-side sibling get_buffer_metrics and from reset_stage_profiling, but the description never names the alternatives, so it relies on the resource noun to differentiate.

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

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

Usage is implied: you reset the counters when you want to clear them (e.g. before a fresh measurement window). The description gives the enabling conditions (write permission, metrics feature) but offers no explicit when-to-use vs when-not, and never references the read counterpart get_buffer_metrics or reset_stage_profiling.

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?

With no annotations, the description carries the full behavioral burden and does disclose the destructive consequence ('discarding any pending proposals'). It still omits whether the reset is reversible, idempotent, or how the voided proposals surface afterward.

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, zero filler, with the action and its side effect front-loaded ahead of the usage condition. 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 zero-argument reset with no annotations and no output schema, the description covers what it does, its destructive effect, and when to invoke it. Only post-reset state or reversibility is left implicit, which is a minor gap.

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

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

The tool takes zero parameters, so there is no parameter semantics to document; baseline 4 applies. The description correctly implies no inputs 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?

States a specific verb+resource ('Reset the architecture agent session') and adds the concrete effect ('discarding any pending proposals'). It implicitly distinguishes itself from the reset_stage_profiling/reset_buffer_metrics siblings by scope, though it never names them explicitly.

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

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

Gives a clear triggering condition: 'Use when the user wants to start over or abandon the current ideation cycle.' It covers context but offers no exclusions or named alternatives among the many propose_*/resolve_proposal 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?

With no annotations, the description carries the full burden, and it does disclose two important gates: write permission is required and the `profiling` feature must be enabled. It does not say whether the reset is reversible, whether it disrupts an in-flight profiling session, or whether counters are zeroed versus deleted, which is a meaningful gap for a mutating 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?

One front-loaded sentence with the action and scope first and the two preconditions parenthetically trailing. No padding, nothing 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 one-optional-parameter reset tool with no output schema, the description covers action, scope, target, and prerequisites, which is largely sufficient. Residual gaps are the post-conditions of the reset (are counters zeroed? does profiling continue?) that an agent might want before calling it on a live instance.

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

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

Schema description coverage is 100% and the single `endpoint` parameter is fully documented in the schema, including the unix://serial:// formats and the AIMDB_CONNECT fallback. The description adds only the notion that the target must be a running instance, so the schema does the heavy lifting.

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

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

States a specific verb+resource+scope: reset stage profiling counters across every record on a running AimDB instance. This is clearly distinct from the read-side sibling get_stage_profiling and from reset_buffer_metrics, so an agent can route without opening either schema.

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

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

The description states prerequisites (write permission, `profiling` feature) and implies this is the mutation counterpart to get_stage_profiling, but never explicitly says when to use this versus reading profiling data or resetting buffer metrics. Usage must be inferred from the verb.

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?

With no annotations, the description carries the full burden and largely succeeds: it discloses that confirm writes state.toml and generates Mermaid/Rust artefacts, that reject is a no-op discard, and that revise discards with a redirect. It omits any statement about permissions, reversibility of an applied change, or failure modes.

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 short clauses, front-loaded with the action and then the three mode outcomes. No filler and no repetition.

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 no annotations and no output schema, the description covers the key side effects an agent needs before invoking. It could say more about what is returned (e.g., the applied result or redirect target) and whether a confirm is recoverable.

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 both the enum and the path-override parameters are already documented in the schema. The description adds little beyond rephrasing the resolution semantics already present in the enum description; baseline 3 applies.

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

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

States a specific verb and resource ('Resolve a pending proposal') and immediately enumerates the three resolution modes with their effects. It is clearly distinct from the propose_* siblings, which create proposals, though it never explicitly names that 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?

The three 'On confirm/reject/revise' clauses effectively describe the behavior tied to each decision, giving the agent enough to choose the right resolution value. There is no explicit when-not guidance, but there is no competing resolve tool to route against.

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?

No annotations are provided, so the description carries the full burden. It discloses the write target and the read-back resource, but the destructive overwrite semantics and default-timestamp behavior live only in the schema, leaving the file-impact disclosure thin for a mutation 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 sentences that are front-loaded with the verb and destination, then the trigger condition, then the restore instruction. The enumerated content list is long but each element maps to a required narrative field, so little is wasted.

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

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

With no output schema or annotations, the description covers what to save, when to save it, where it lands, and how to restore it. Only the destructive overwrite caveat and pagination/file-growth behavior are left implicit.

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

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

Schema description coverage is 100%, so baseline is 3. The description restates the entry structure ('what the user is building, key question...') and mode intent, but adds no syntax or format detail 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?

States a specific verb (persist) and resource (ideation context and design rationale) plus the concrete destination (.aimdb/memory.md). An agent can distinguish it from proposal/record siblings, which mutate schemas rather than memory.

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

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

Gives a clear trigger ('Call this after every confirmed proposal') and a companion lifecycle step ('On session start, read aimdb://architecture/memory to restore this context'). No explicit when-not or alternative tool is named, but no close sibling competes for this role.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the write-permission precondition, but that is largely duplicated by the schema's 'must be writable' description, and it says nothing about overwrite semantics, persistence, downstream effects, or failure behavior on a non-writable record.

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 sentences, zero padding, with the core action front-loaded and the permission constraint second. Nothing here fails to earn 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 simple three-parameter setter with no output schema, the description covers what and on what, but omits write semantics (replacement vs merge), persistence, and error behavior. It is adequate but leaves the mutation contract underspecified.

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% (value type constraint, endpoint formats, record_name writability), so the schema already carries parameter meaning. The description adds no additional parameter detail, making the documented baseline of 3 appropriate.

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

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

States a specific verb+resource ('Set the value of a writable record') and scopes it to write-permitted records, which distinguishes it from read siblings like get_record and list_records. It does not differentiate itself from mutation siblings such as rename_record or remove_record, so it falls short of a 5.

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

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

The precondition 'Only works for records with write permissions' implies when the tool is applicable, but no alternative is named and there is no explicit when-not guidance (e.g., use rename_record to change the name, resolve_proposal for schema changes). Usage is inferable rather than stated.

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

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

With no annotations, the description carries the full burden. It usefully discloses the categories of conflicts found and implies a non-mutating comparison, but never states whether the tool only reads or can remediate, whether it requires connectivity to the instance, or how large a report can be. Partial disclosure.

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 compare-and-report action is front-loaded and the detection list follows economically.

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?

There is no output schema, so the description usefully sketches the return value ('a conflict report') and its content categories. Given only two optional, well-documented parameters and no annotations, this is close to complete, though a note on read-only semantics would close the remaining gap.

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

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

Schema description coverage is 100%, so both endpoint and state_path are fully documented in the schema, including the AIMDB_CONNECT fallback and the default state.toml path. The description adds no parameter-level detail beyond that, so baseline 3 applies.

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

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

States a specific verb (Compare/Validate) and two specific resources (state.toml and a live AimDB instance), and enumerates what it detects: missing records, buffer type mismatches, capacity differences, connector mismatches. This clearly separates it from mutating siblings like propose_* and read siblings like get_instance_info.

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 validation intent implies when to use it (checking drift between a declared state file and a running instance), but there is no explicit when-to-use statement, no prerequisites, and no routing to alternatives such as get_instance_info. Usage is inferable but not stated.

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