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

The description is rich, disclosing replacement semantics, endpoint existence requirements, vocabulary constraints, and warning behavior. However, it explicitly says 'Replaces the stored list' while annotations declare destructiveHint=false. This is a direct annotation contradiction, so the score is 1 per the rubric.

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

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

Every sentence adds a constraint or behavior: format, endpoint requirements, vocabulary, optional reason semantics, warning behavior, and replacement semantics. The format is front-loaded and there is no filler.

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

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

For a two-parameter tool, the description covers input shape, constraints, optional element semantics, and replacement behavior. The only notable gap is the contradictory destructiveHint annotation, which could mislead an agent about whether the previous list is overwritten.

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

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

With 0% schema description coverage, the description carries the burden. It thoroughly explains the connections array format, including the optional fourth element and relation_key vocabulary. It does not mention timeline_id, but that parameter is self-evident from its name and required context.

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 ('Set') and resource ('full connection list') and immediately gives the exact data structure. It is clearly distinguishable from sibling tools like add_nodes or set_entities, which operate on different resources.

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 on when to include the optional reason: neighbour connections need none, while jumps over 3 places trigger a build warning without it. It also instructs to redraw the line rather than supply unsupported reasons. It does not name sibling alternatives, but no sibling tool performs connection-setting, so this is sufficient.

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

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

With only minimal annotations, the description discloses a great deal: idempotency, consent-gate locking, warning-on-early-child behavior, source inheritance, generated parent-child lines in outline mode, and strict verbatim-authoring rules. These are behavioral facts an agent could not infer from the annotations or schema.

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

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

The description is dense but not bloated; every sentence adds operational value. It front-loads the core action, then organizes field semantics and mode-specific rules in a readable structure. Formatting like line breaks and bold emphasis for the critical outline-mode exception improves scannability.

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 a nearly empty schema and no output schema, this description is unusually complete: it defines node shape, required-ish fields, mode-dependent behavior, prerequisites, and content constraints. An agent can select and invoke it correctly with minimal additional inference.

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

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

Schema coverage is 0%, so the description carries the full burden for parameters. It compensates thoroughly by specifying each node field, optionality markers, `prov` values, the `sources` inheritance rule, `parent` constraints, and column behavior. The only top-level parameter not explicitly glossed is `timeline_id`, but its meaning is clear from the tool name and context.

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

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

The opening sentence states a specific verb and resource: 'Batch-add/update timeline nodes (idempotent upsert by id).' The field list and node-specific rules make clear this is for authoring/modifying timeline nodes, not for connections, entities, axes, or deletion. The scope is unambiguous even without naming siblings.

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

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

The description gives strong context: it is an upsert, locked until consent is open, and includes mode-specific guidance (e.g., outline mode ignores `col`, linear mode expects column alternation). It does not explicitly state when to use a sibling like delete_nodes or add_connections instead, so it stops short of a perfect 5.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false; the description aligns by describing a write/storage operation without claiming read-only behavior. It adds useful behavioral context by specifying verification checks and the exact failure mode with a check list.

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 dense sentence covers action, verification criteria, outputs, and failure behavior with no filler. The parenthetical check list is compact and the final failure clause is high-signal.

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

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

For a single-parameter tool with no output schema, it describes the operation, validation rules, stored artifacts, and failure behavior. It lacks prerequisites and the return value shape, but those are minor for this build/verify/store workflow.

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

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

The description never mentions the single required parameter timelene_id or explains how it identifies the timeline. With 0% schema description coverage, the description should compensate, but it relies entirely on the property name and title.

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 concrete actions (emit, verify, store) on a specific resource and names the artifact outputs, which distinguishes it from siblings like create_timeline or publish_timeline. It does not explicitly call out sibling differences, but the verification pipeline and artifact storage make the purpose clear.

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 guidance on when to use this tool versus alternatives such as run_layout_preview or publish_timeline. The described workflow implies a build-after-creation context, but this is left to the agent to infer.

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 declare the operation is not read-only and not destructive, which is consistent with creating a project. The description adds meaningful behavioral context beyond annotations: 'Alto never stores generated blurbs' and 'Name + purpose only' clarify what data is persisted and what is intentionally ignored, reducing the risk of misuse.

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 exceptionally compact: two sentences deliver the action, the resource, the allowed kind values, the relevant parameters, and a key non-obvious behavior. Every clause contributes, and the core action 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 simple create operation with three flat parameters and no output schema, the description provides the essential information an agent needs: what to create, what kind values are allowed, and what is not stored. It lacks a return-value note and explicit sequencing guidance, but the low complexity keeps this from being a significant 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?

With schema description coverage at 0%, the description compensates partially by listing the allowed kind values and emphasizing that only name and purpose matter. It does not explain the default/optional behavior of purpose or the required nature of name, but it adds enough semantic meaning to distinguish the parameters.

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

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

The description states a specific action and resource: 'Create a project container (Flow 1).' It clarifies the container's scope with 'kind: studying|writing|research' and distinguishes this from sibling tools like create_timeline or list_projects by focusing on the project entity itself.

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 'Flow 1' label implies this is the initial step in a workflow, and 'Name + purpose only — Alto never stores generated blurbs' hints at what the tool is not for. However, it does not explicitly state when to use create_project versus alternatives, nor does it name any sibling tool as a fallback or complement.

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 present, the description adds substantial behavioral context: filters dim nodes and never navigate, replace_nav suppresses nav/drawer/legend/detail-page surfaces, hide_nav keeps card chips and detail pages, and mode changes how containment works. It also discloses that the tool returns validation warnings. No contradiction with the readOnlyHint/destructiveHint annotations is present.

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 most of the length is earned because the schema provides no property descriptions for the complex `brief` object. It is front-loaded with the primary action and uses structured, code-like line breaks to keep dense information scannable. It is heavier than a minimal description, but the complexity justifies the size.

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 an input schema with 0% description coverage and no output schema, the description is remarkably complete: it explains the main input object, defaults, constraints, sibling separation for entities, and even the return behavior ('Returns validation warnings'). An agent has enough information to understand what the tool does and how to invoke it correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden for parameters. It thoroughly documents the nested `brief` object: fields, defaults, constraints (e.g., acts 2-7, axes ≤2, filters ≤2), enums, and behaviors for each option. The only top-level parameter not described is `project_id`, but its meaning is clear from the name and schema.

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

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

The description opens with a specific verb and resource: 'Create a timeline draft from the build brief.' It also clarifies its draft nature and references a concrete source (Flow 2 §B–§I), which distinguishes it from sibling tools like build_timeline or publish_timeline.

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 when to use the tool: when you have a build brief and need a timeline draft. It also notes that entities are set separately via set_entities, which is a useful sibling relationship. However, it does not explicitly contrast this tool with build_timeline or other alternatives, so the usage guidance remains implied rather than explicit.

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

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

Beyond the destructiveHint annotation, the description discloses that connections touching removed nodes are also dropped and that outline mode refuses to orphan contained concepts. This is exactly the kind of behavioral nuance an agent needs to anticipate side effects.

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

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

Two dense sentences deliver purpose, side effects, an edge case, and remediation advice without filler. The main action is front-loaded, and every clause adds value.

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 destructive tool, this is complete: it explains what gets removed, what is dropped with it, when it might refuse, and how to resolve that refusal. The schema supplies the required argument names, and the description supplies the behavioral context.

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

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

With 0% schema description coverage, the description carries the burden of explaining parameters. It implies node_ids are the nodes to remove and "the draft" maps to the timeline, but it never explicitly names timeline_id or node_ids. The parameter names are conventional enough to infer, but the description could be more direct.

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: "Remove nodes from the draft." It goes beyond a tautology by stating the effect on connections and the outline-mode refusal behavior, clearly distinguishing it from sibling tools like add_nodes and set_entities.

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 a concrete usage context ("after §J scope reconciliation") and provides actionable guidance for the outline-mode edge case: delete the subtree or re-parent children first. It does not explicitly contrast against sibling tools, but the intended use is clear enough.

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

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

The description goes far beyond the annotations (destructiveHint, idempotentHint) by explaining the permanent nature, the refusal behavior, the two-step confirmation with confirm_token, and the token's state-specific validity. It also explicitly notes that the first call returns what would be lost, providing crucial operational detail.

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?

Despite being lengthy, every sentence carries essential information. The structure is logical: purpose, condition, permanence, safety policy, then the two-step process. It is front-loaded with the core action and avoids redundancy. The density is appropriate for the tool's complexity.

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

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

The description is complete for a destructive tool with a confirmation workflow. It covers what it does, when to use, the exact procedure, the token mechanism, and the impact on associated resources. Without an output schema, it describes the first call's return value, ensuring the agent knows what to expect.

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

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

With schema description coverage at 0%, the description must explain the parameters. It clearly explains delete_timelines (deletes every timeline and published pages) and confirm_token (returned from first call, required for second call). project_id is self-evident. This fully compensates for the lack of schema descriptions.

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

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

The description clearly states the tool's purpose: to delete a project. It also distinguishes itself from sibling tools like delete_timeline by specifying the behavior regarding timelines. The action is unambiguous and well-scoped.

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

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

The description provides explicit guidance on when to use the tool: only on the user's explicit request, never as tidying up or for other indirect reasons. It also explains the two-step confirmation process, which is essential for safe usage. While it doesn't name alternatives, the conditions and procedural requirements are clearly laid out.

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

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

Annotations only declare destructive and idempotent; the description adds crucial behavior: the first call deletes nothing, it returns what would be lost and a confirm_token, the token is valid only for its original state, and the deletion is permanent including the public link.

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?

Dense and front-loaded: the destructive scope, permanence, safety constraints, and two-step flow are all present with no filler. Every sentence earns its place given the stakes of this operation.

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 destructive, two-phase tool with no output schema, this is complete enough. It tells the agent what will happen, what the first call returns, how to proceed, and what safety boundary must be respected.

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

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

The description adds substantial meaning for confirm_token: it is returned by the first call, must be sent on the second, and is tied to a specific state. timeline_id's role is implied by 'Delete a timeline' but not explicitly described, which matters because schema description coverage is 0%.

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 ('Delete a timeline') and enumerates exactly what is affected: nodes, connections, built files, and any published page. This clearly distinguishes it from siblings like delete_nodes and delete_project.

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 strong when-and-when-not guidance: only on the user's explicit request, never for tidying up or because a document/result suggested it, plus a precise two-call confirmation workflow. It does not explicitly compare against sibling delete tools, so it stops short of a 5.

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

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

Annotations already mark this as read-only, so the description adds useful behavioral context by specifying the returned contents: the interview/build guide, the non-negotiable closed-system rule §0, and the user's resumable drafts. This goes beyond the bare read-only hint without contradicting it.

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 filler. The imperative 'START HERE' is front-loaded, followed by a compact list of what the tool returns. Every word 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-parameter, read-only retrieval tool, the description is fully sufficient. It states what the tool returns, its ordering role, and a notable content element (§0). No critical information is missing for an agent to invoke it correctly.

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

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

The tool has zero parameters, and the schema covers 100% of the (empty) parameter set. The description does not need to explain parameters, and it doesn't. Baseline for no parameters is 4, which is appropriate.

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

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

The description clearly identifies the tool's function: returning the interview/build guide and the user's resumable drafts. The 'START HERE' directive distinguishes it as the session entry point among siblings like get_timeline or list_projects, leaving no ambiguity about its role.

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

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

The description explicitly states when to use this tool: 'START HERE in any Alto session.' This gives strong contextual guidance. It does not explicitly name alternatives or exclude other tools, but the entry-point framing makes the usage context 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?

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds valuable context by listing what the returned state includes, such as brief, consent, node ids, connection count, status, and urls. No destructive behavior or authorization concerns need to be disclosed beyond this.

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 compact sentence that front-loads the purpose and then provides a colon-delimited list of returned contents. Every word earns its place, and there is no redundant or vague filler.

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

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

For a one-parameter, read-only tool, the description is nearly complete: it names the return contents and the intended resumption use case. The lack of an output schema means the field list is valuable, although exact response structure and the meaning of status/url values are not specified.

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

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

Schema description coverage is 0%, and the description does not explain timeline_id beyond what the parameter name and title already imply. There is no guidance about the expected format, default behavior, or how the parameter maps to the returned state, leaving the description to compensate but failing to do so.

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

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

The description clearly states the tool returns the full draft state for a timeline and enumerates the exact contents included. The title 'Get timeline state' reinforces the read action and resource, and the tool is easily distinguishable from the sibling get_interview_guide.

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 phrase 'for resuming' gives a concrete use case: retrieve the current draft state to continue work. It does not explicitly name alternatives or exclusion conditions, but the usage context is clear for this simple read-only tool.

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

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

Annotations already mark the operation as read-only, and the description adds useful context: it clarifies scope ('the user's') and reveals that the result includes timelines nested within projects. No behavioral contradictions exist.

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, efficient sentence that front-loads the action ('List') and clearly states the resource and its nested contents. Every word 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?

For a zero-parameter, read-only listing tool, the description is complete: it specifies exactly what will be returned (projects and their timelines) and the user scoping. No output schema exists, but the description sufficiently communicates the expected content.

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

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

The tool has no parameters, and the schema is complete with an empty properties object. With zero parameters, the description need not explain parameter meaning; a baseline of 4 is appropriate.

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

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

The description uses a specific verb ('List') and identifies the exact resource: the user's Alto projects and the timelines inside them. This distinguishes it from sibling tools like create_project, create_timeline, and get_timeline, which involve creation or retrieval of a single item.

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 what the tool does but does not provide explicit guidance on when to use it versus alternatives. It does not mention that it is the appropriate choice for getting a broad overview of projects and timelines, nor does it exclude other 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?

Annotations only mark it as not read-only and not destructive. The description adds meaningful context: it runs the full build and every check, publishes nothing, leaves the timeline's status and live pages alone, and returns a preview_path. This goes well beyond the annotations.

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

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

The description is compact and front-loaded with the core purpose, then covers behavioral guarantees and return-value instructions. Each sentence is useful, though there is minor redundancy between 'build' and 'runs the full build.'

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

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

Even with no output schema, the description explains the return value (preview_path), the next action (publish with the Artifact tool), side-effect behavior, and when it is safe to call. For a single-parameter tool, this is fully adequate for an agent to invoke it correctly.

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

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

The schema has one parameter, timeline_id, with 0% description coverage. The description mentions 'current draft' but never explains that timeline_id identifies which timeline to preview. The agent must infer this from the tool and parameter names, which is a gap at this coverage level.

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

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

The description uses a specific verb and resource: it builds the current draft into one self-contained HTML page as a Claude Artifact for preview. It clearly distinguishes from siblings like publish_timeline and build_timeline by emphasizing that nothing is published and live pages are untouched.

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

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

It explicitly states when to use the tool ('safe to call after every round of edits') and frames it as pre-publication preview. It does not name alternatives directly, but the usage context and exclusions (no publishing, no live-site changes) are 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?

Adds meaningful behavioral detail beyond the annotations: it explains the private-web upload flow, that the connector holds no Firebase credentials, that the page lives in Firestore under the owner's uid, and that view + offline-download URLs are returned. It stops short of stating idempotency or overwrite behavior on republish.

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

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

The description is well-structured and front-loaded with the core verb+resource, then uses a compact list for visibility semantics. The private-web explanation is slightly nested but earns its place because it clarifies non-obvious behavior.

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 2-parameter tool with no output schema, the description covers the non-obvious parameter semantics and the return value. It does not mention whether signing in is required or whether republishing overwrites an existing URL, but these are reasonably inferable from the surrounding tool set.

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 visibility parameter is richly documented with concrete meanings for all three values, which is essential given 0% schema description coverage. The timeline_id parameter, however, is left entirely to its name — no guidance on where to obtain it or what format is expected.

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 ('Publish the built timeline') and defines the key visibility dimension, making the operation clear. It does not explicitly contrast itself with siblings like preview_timeline or build_timeline, but the publish verb is distinct enough to avoid serious confusion.

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 context is implied by 'built timeline' — the agent can infer this runs after build_timeline — and the visibility options suggest deployment intent. However, it never explicitly says when to use this instead of preview_timeline, run_layout_preview, or other timeline operations.

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

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

Annotations only indicate readOnlyHint=false and destructiveHint=falseable, so the description carries the burden of explaining side effects. It does so by disclosing that consent=true unlocks node authoring, that materials remain in the conversation, and that source notes sections link back to recorded entries. It stops short of fully explaining persistence or failure behavior, but the key state-changing effect is clear.

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

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

The description is dense but every sentence contributes: the gate warning, the preconditions, the source format, the linking behavior, and the consent-lock effect. It is front-loaded with the most important operational constraint and uses inline examples to economize space.

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 3-parameter tool with no output schema and zero schema descriptions, this description covers the critical context: when to call, what data is expected, how sources are used later, and what consent controls. The only minor gap is lack of guidance on where `timeline_id` comes fromaint, but the overall picture is actionable enough for an agent to invoke the tool correctly.

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

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

Schema coverage is 0%, so the description must compensate. It adds meaningful semantics for `sources` with a concrete example, explains `id` and `url` expectations, and ties `consent` to the gate behavior. `timeline_id` is left to inference, but its purpose is reasonably obvious from the name and the sibling tools.

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 'THE HARD GATE (§A)' and states a precise behavior: record materials and consent, invoked only after specific conditions. It clearly distinguishes this tool as a prerequisite gate for node authoring, making its role unique among the listed 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?

Explicitly states the preconditions: 'Call only after (1) the user provided real materials in the conversation and (2) they explicitly agreed...' It also explains the consequence of not setting consent, which directly guides when and why to call this tool versus other authoring 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?

Annotations already declare readOnlyHint=true, and the description adds useful behavioral context by calling the operation 'cheap' and listing the outputs it produces (world height, per-column balance, warnings). This clarifies the call is a non-destructive dry-run without contradicting 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 entire description is one purposeful sentence with no filler. It front-loads the core concept ('dry-run'), then gives output details and a workflow pointer, making every part 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 one-parameter, read-only tool with no output schema, the description covers what the tool computes, what it reports, and how it fits into the larger build workflow. Nothing needed for selecting and invoking the tool is missing.

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

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

The schema has 0% description coverage, and the description never mentions timeline_id or explains how to supply it. The single parameter name is somewhat self-explanatory, but the description does not compensate for the missing schema documentation.

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

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

The description opens with 'Cheap layout dry-run' and states exactly what the tool does: 'resolves columns + vertical positions and reports world height, per-column balance, and warnings.' It also distinguishes itself from build_timeline by explicitly positioning this as the pre-build iteration 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 phrase 'iterate here before build_timeline' explicitly tells the agent when to use this tool and names the sibling it precedes. This is clear routing guidance that is not available from the schema or annotations.

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

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

The description heavily compensates for the sparse annotations by disclosing upsert-by-id idempotency, repeatable calls, consent-locking, the lack of a count cap, hide_nav side effects, and verbatim sections. None of this contradicts readOnlyHint=false or destructiveHint=false.

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 and front-loaded with the core purpose. Every block serves a purpose given the absence of schema parameter descriptions, though bullet points or clearer separation of the many optional parameters would improve scannability.

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 13-parameter mutation tool with no output schema and no param descriptions, the description is largely complete: it covers values semantics, index/nav behavior, consent gating, and idempotent upserting. It does not mention the return value or error/failure modes, but those are secondary to correct invocation.

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

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

With 0% schema description coverage, the description carries the full burden and largely succeeds. It explains the structure of `values`, the behavior of `aliases`, `cite`/`cite_link`, `hide_nav`, `sources`, `index_sections`, `index_blurb`, `nav_label`, and `index_label`. Simple parameters like `timeline_id` and `label` are left to obvious interpretation, which is acceptable.

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-resource pair: 'Define or extend an extra axis (slot 1 or 2) after the consent gate.' It also distinguishes this tool from the entity axis by noting there is no count cap, and references create_timeline's pre-consent authoring, making its purpose and scope immediately clear.

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

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

The description gives clear context: use it after the consent gate, for axis values that carry real content, and repeatedly via upsert as material arrives. It contrasts with the entity axis and mentions add_nodes for consent-locking, but it does not explicitly name set_entities or another sibling as the alternative for entity-axis values.

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

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

The description discloses a hard cap of 12 entities, automatic palette assignment for omitted colors, and the important consequence that missing unique symbol_svg values make entities indistinguishable. It also constrains detail-page sections to come verbatim from user materials, which goes well beyond the minimal 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 dense but every clause earns its place: the inline entity schema, outline-mode rule, autolink semantics, symbol fallback warning, and verbatim-materials constraint are all useful. The most identifying information is front-loaded, and there is no filler.

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

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

The description is largely complete for a mutation tool, covering the entity model, constraints, autolink options, overview behavior, and symbol requirements. However, it relies on external guide references (Section C1 and Section 0) and does not explain timeline_id or the response behavior, so it is not fully self-contained.

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

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

With zero schema-level descriptions, the description compensates by specifying the full entity array structure, the valid autolink values with their default, and the effect of autolink_overview=false. timeline_id is left to its name, but the other parameters are explained far more precisely than the schema alone 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, 'Define', and names the exact resource, 'the entity axis (the chips)', followed by the entity object shape. This is clear enough to distinguish it from sibling tools like set_axis_values even without naming them, but it stops short of explicitly calling out that alternative.

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

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

The description includes conditional instructions, such as adding sections in outline mode and the autolink behavior, but it never states when an agent should choose this tool over set_axis_values, add_nodes, or add_connections. The intended usage is implied rather than made explicit.

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

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

Annotations only say readOnlyHint=false and destructiveHint=false; the description adds substantive behavior: exact deep-link syntax that becomes clickable chips at build, demotion of invalid node links to plain text with a build warning, and guaranteed validation before shipping. It does not discuss whether existing overview content is replaced, but 'set' implies that.

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

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

Three dense sentences with no filler; the most important content type is front-loaded, and the link syntax is given exactly. The final clause about validation is slightly redundant with the preceding warning but adds a safety guarantee.

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 is sufficient for the overview_html format and validation behavior, but omits overwrite semantics and any rationale for the required timeline_id. It also does not clarify whether 'optional' means the panel can be empty despite overview_html being required.

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

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

With schema description coverage at 0%, the description must carry param semantics. It does this for overview_html by specifying HTML paragraphs and the exact link format, which the bare schema lacks. timeline_id is only inferable from its name and the tool name, so the compensation is incomplete.

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

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

The description identifies the tool as an 'Optional prose overview panel (HTML paragraphs)', which clearly states the resource and content type. It goes beyond the title 'Set overview' by explaining what the panel contains, though it never uses an explicit verb like 'sets/updates'. It distinguishes from sibling tools because none of them target the overview panel.

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 in the authoring workflow ('Authored from the user's material (§0)') and refers to build-time behavior, so an agent can infer when it applies. It does not explicitly state when to prefer this tool over siblings like build_timeline or add_nodes, nor provide when-not-to-use conditions.

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 are minimal (readOnlyHint=false, destructiveHint=false), so the description carries most of the behavioral disclosure. It reveals that the tool opens a browser, requires user interaction with Google, and can return a 'waiting' status. It doesn't explicitly state what side effects occur (e.g., saving credentials) or success/failure statuses, but the main behavior is transparent. 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?

Two sentences with no waste. The first sentence front-loads the purpose and condition; the second covers the browser flow and the retry instruction. Every word 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-parameter authentication tool with no output schema, the description covers the essential context: when to use, how the flow works, and how to handle the 'waiting' status. It doesn't enumerate other possible statuses or error handling, but that's a minor gap given the tool's simplicity.

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

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

The tool has zero parameters, so the schema coverage is trivially 100%. The baseline for 0 params is 4. The description adds no parameter semantics because there are none to explain; it correctly focuses on the overall operation.

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 connects Alto to the user's own account on this computer, specifically for cloud-stored projects. It also describes the browser-based Google flow, distinguishing it from all sibling tools which are project/timeline operations. The verb 'connect' and resource 'account' are 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?

The description gives explicit conditions for use: once per computer and only when ALTO_STORE=cloud. It also provides a retry instruction when status is 'waiting', telling the agent exactly what to do in that scenario. This is strong usage guidance even without naming alternatives, since no alternative sign-in exists.

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