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

Annotations only declare readOnlyHint and openWorldHint; the description adds that output is Markdown and that long pages require offset-based paging to continue. That paging behavior is the kind of operational detail annotations cannot carry, though caching behavior and page-size limits are left to 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?

Three short sentences with the core action front-loaded and the input format plus paging caveat following. No filler, though the example path could have been trimmed given the schema already describes the format.

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

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

No output schema exists, so the description's note that content returns as Markdown and may need paging is the right coverage to provide. Size limits, defaults and refresh are handled in the schema, leaving little an agent needs that is missing.

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

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

Schema coverage is 100%, so all four parameters are already documented in the schema. The description's mention of path format and offset paging duplicates rather than extends that, and it says nothing about `refresh` caching semantics beyond what the schema states. 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 ('Read one official Effect House documentation page as Markdown') and the singular 'one page' implicitly separates it from the docs_search sibling. It stops short of naming docs_search, so the distinction must be inferred from 'one page' 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?

The description gives the accepted input forms (full URL or /learn/ path) with a concrete example, which implies usage, but never says when to choose this over docs_search or workspace_read. No exclusions or prerequisites are offered.

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

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

Annotations already cover safety (readOnlyHint) and reach (openWorldHint), and the description adds substantive behavior beyond them: matching is done on page paths, with titles/text only for pages already read or indexed, and the return value is URLs rather than content. That indexing caveat is exactly the kind of non-obvious trait that prevents a wrong invocation. It doesn't mention ranking or empty-result behavior, keeping it below 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 tight sentences: the first establishes the corpus and coverage, the second establishes matching behavior and the handoff to `docs_read`. No filler, and the most decision-relevant information (where it searches and that it returns URLs) 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?

With no output schema, the description carries the burden of describing returns and does so (URLs). Combined with full schema coverage and annotations covering safety and open-world scope, an agent has everything needed to call this correctly and chain it into `docs_read`.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning about what `query` is matched against (paths plus, conditionally, titles and text), which is not in the schema. The `section` restriction is only indirectly hinted at via the enumerated content areas, and `limit` is left entirely to 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 ("Search the official Effect House documentation at effecthouse.tiktok.com/learn") and enumerates the covered content areas, so an agent knows exactly what corpus is being searched. It also differentiates itself from the sibling `docs_read` by explaining that results are URLs to be passed onward.

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 makes the search→read workflow explicit ("Returns URLs to pass to `docs_read`"), which tells an agent exactly how this tool fits with its nearest sibling. It stops short of stating exclusions, e.g. that it cannot fetch page bodies or that offline/non-doc queries won't work, so it is not a full when/when-not statement.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioural context that this tool actively probes live editors to gather heartbeat/health and that it reports kernel state and workspace folder. It does not disclose cost, latency, or what happens when no editor is running, which matters for a live-probing 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?

Front-loads the purpose, then lists returned data, then closes with the decisive usage guidance. Dense but every clause carries information; the long enumerative sentence is slightly heavy but earns its length given there is no output schema.

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

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

With no output schema, the description correctly compensates by listing the fields an agent will receive. It covers the core discovery use case well; only edge behaviour (no editors found, partial failures) is unaddressed.

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 the single includeProject parameter is fully documented in the schema, so baseline 3 applies. The description's mention of 'the project each one has open' hints at the same concept but adds no semantics about the boolean's default or cost of enabling it.

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 (find) and enumerates the exact resource set it resolves: installation/version, running editor instances with port, heartbeat and health, the open project, kernel state and workspace folder. That enumeration is unusually concrete, but it never distinguishes itself from the sibling 'status' tool, which appears to overlap.

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?

'Call it first when a cell cannot reach the editor' gives an explicit, actionable trigger condition, effectively declaring this the entry-point diagnostic. What's missing is any exclusion or hand-off to the sibling 'status' tool, which an agent could easily confuse with this one.

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 non-destructive, idempotent, closed-world, and the description reinforces idempotency by spelling out the no-op path when the editor is running. It also discloses blocking behavior ('wait until its automation server answers'), which annotations do not cover. It stops short of saying what happens on timeout even though `waitSeconds` bounds 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?

Three short sentences, front-loaded with the primary action and followed by the conditional behavior and the exclusion. No filler; every sentence carries decision-relevant 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 two-parameter, no-output-schema launcher, the description covers what happens, when it is a no-op, and the alternative. The only gap is failure/timeout behavior, which is minor given `waitSeconds` is fully documented in the schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real conditional meaning: supplying `project` opens that project, omitting it only launches the editor. `waitSeconds` is left entirely to 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 concrete verb and resource: 'Open Effect House and wait until its automation server answers.' It also distinguishes the optional-project variant, so an agent can tell this apart from `run` and `status` 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 covers the exclusion case ('When Effect House is already running nothing is launched') and names the correct alternative for that case ('open projects from a `run` cell with `eh.project.open(path)`'), plus a pointer to `help('project')`.

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 does disclose exactly what is lost (session values and connection), which is the key behavioral fact for a reset. However, it omits whether the reset is irreversible, what happens to in-flight operations, and what state the kernel is left in, all of which matter for a destructive operation.

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 no filler. It is arguably under-specified rather than over-long, and the "eh" typo is a minor quality blemish.

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, annotation-free, output-schema-free tool, the agent still needs to know what to do after a reset (e.g., relaunch via the launch sibling) and whether subsequent calls will fail. None of that lifecycle context is provided.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter detail is needed or missing.

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 pairs a specific verb ("Discard") with a specific resource ("kernel state") and clarifies scope with parenthetical detail ("session values and connection"). This is clear enough to distinguish it from siblings like launch/run/status, though it never explicitly names an alternative and the typo ("eh") slightly mars readability.

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 call reset versus launch or status, nor any preconditions (e.g., whether a kernel must be running first). The agent must infer usage entirely from the tool name and the parenthetical.

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 real work: it discloses that cells execute against a live editor via a privileged `eh` API (i.e. side effects are possible), states the out-of-band prerequisite, reports current unavailability, and points at remediation tools. Still missing: failure behavior, whether/timeout effects, and what a run yields (logs, return value).

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 in the first clause, and the parenthetical groups the prerequisite and sibling routing efficiently. Minor waste: the 'kernel is not available right now' status claim duplicates runtime information that belongs in a status check and may be stale inside a static 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?

For an execute-arbitrary-code tool with no output schema and no annotations, the definition covers prerequisites and alternatives but never explains what a successful run produces (return value, output channel, how cell results surface). That gap matters for an agent deciding between `code` and `path` and interpreting 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?

Schema description coverage is 100% and the schema already states the mutually exclusive `code`/`path` rule, timeout semantics, and optional save name. The description adds no parameter-level 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 and resource: runs a JavaScript cell in the Effect House `eh` kernel driving the open editor. The generic name `run` is disambiguated by the body, and it names sibling tools (`instances`, `launch`) that cover adjacent concerns, though it does not contrast against `reset` or `status`.

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 routing: if the kernel is unavailable, call `instances`; to open the editor, call `launch`. Prerequisite (Effect House must be open) is stated explicitly. It lacks an explicit 'prefer X over run when...' rule or guidance on choosing `code` vs `path` beyond the schema.

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 burden alone. It implies a read-only diagnostic call and enumerates the returned facts, but says nothing about cost, latency, whether it starts or contacts a kernel, or what happens if no kernel is running — meaningful gaps for a status tool with zero annotation coverage.

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 that maps directly onto the tool's purpose with no padding. It loses a point for the typo ('eh') and slightly clipped phrasing that reads as rough rather than precise.

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, annotations, or parameters, the description is the only source of truth about results, and its field list ('cells run', 'instance', 'project', 'connection') is only indicative — types, units, and format are undefined. Adequate for a zero-arg status call, but it leaves the return shape 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?

The tool takes zero parameters, so the baseline is 4. The description correctly implies a no-argument invocation and adds nothing misleading about inputs.

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 (Report) and resource (kernel status) and enumerates the fields returned: cells run, instance, project, connection. The agent can distinguish it from siblings like reset, launch, or run without opening the schema, though the description never explicitly names 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?

There is no explicit statement of when to call this versus alternatives such as `instances` (which plausibly also reports instance information) or `reset`. The intent to check current kernel state is only inferable from the verb 'Report', and no preconditions 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds genuinely useful operational context: the workspace is read-only-ish local content and paths must resolve inside the workspace root. It does not mention how long files are truncated or that paging exists, though the schema's offset/maxChars cover that mechanically.

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, front-loaded with the capability, then path rules, then the selection condition. The workspace enumeration is dense but load-bearing, since it tells the agent what is actually reachable.

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?

A simple read-only tool with all three parameters documented and safety covered by annotations; the description supplies the path-resolution rule and the eligibility condition. The only gap is the shape of a folder listing (names vs. entries), which no output schema documents.

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

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

Schema coverage is 100%, so baseline is 3; the description earns the bump by stating the path resolution rule (relative to workspace root, or absolute but inside it), which the schema's example does not convey. offset/maxChars semantics are left entirely to the schema, which documents them adequately.

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 concrete verb pair (read file / list folder) against a named resource (the eh kernel workspace) and enumerates the workspace sections it covers (AGENTS.md, flow/, skills/, APJS/, reference/, Planning/). The boundary with docs_read/docs_search is only implied by the word 'workspace' rather than stated, keeping it just 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?

Gives an explicit triggering condition: 'Use it when your client cannot read local files.' That is a real selection rule rather than vague context. It does not name the alternative (docs_read) for packaged documentation, so the exclusion side is incomplete.

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