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

With no annotations supplied, the description carries the full behavioral burden and does so well: it states the tool changes nothing, starts nothing except `claude --version`, never reads a token's value, and does not start the agent — a precise side-effect profile that an agent could not infer from the empty schema. It also discloses output shape (one fix line per problem, final line is the command to 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?

The purpose and the no-side-effects guarantee are front-loaded, and each remaining clause adds a checklist item or a safety fact. It is a dense run-on paragraph, though, with slightly awkward quoting around "Your agent" that costs some readability.

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, and the description compensates by explaining the result format — per-problem remediation lines and a final runnable command — plus the readiness condition. For a zero-parameter diagnostic tool this is complete enough to call and interpret without further information.

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

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

The tool takes zero parameters, so the baseline is 4; the description correctly notes the invocation example is `{}`, confirming no arguments are needed. No further parameter meaning is required.

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?

"Check this PC before the person starts Your agent" gives a specific verb and resource, and the description enumerates exactly what is inspected (Node.js, Claude Code version, plainhub command, free ports, running agent, paired browsers, GitHub token). It's clear what the tool does, though it never explicitly names a sibling tool it should be preferred over, leaving the distinction from plainhub_open/plainhub_auth to be inferred from usage context.

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 it first when the user wants to set up Your agent or ask Claude Code from their phone, and again after fixing something" gives a clear trigger and a re-run condition. There is no explicit when-not guidance or named alternative, which keeps it at 4 rather than 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?

No annotations are supplied, so the description carries the full burden, and it does substantial work: it discloses that the tool is a one-shot bootstrap, that it opens an external GitHub page, that the token is persisted ('it is saved, not shown'), and it recommends a least-privilege fine-grained token with Contents read/write. What it omits is the outcome shape (whether it returns a URL to hand the user, or what happens if already authenticated), which matters for a no-annotation 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-loaded with the action, then the routing condition, then the security guidance, then the parameter caveat. Every sentence carries information, though the security rationale appears twice ('the token never appears in this chat' and 'tokens pasted into a chat stay in its history'), which is slight 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?

With one optional parameter, no annotations, and no output schema, the definition covers what an agent needs to decide whether and how to call it, including the recommended token scope and the safe handoff path. The gap is the post-call contract: nothing says what the tool returns or how to proceed once the user saves the token.

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 semantics beyond the schema: it establishes the preferred flow (empty call, user runs 'plainhub auth' in their own terminal) and frames the token parameter as an exception rather than the normal path. The example '{}' clarifies that the parameterless invocation is the expected default.

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?

Names a specific action and resource: 'sign PlainHub in to GitHub: opens the GitHub page that creates a token.' An agent can immediately distinguish this from plainhub_auth_status (which checks state) and from the ledger 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?

Gives an explicit trigger tied to a sibling: 'Use it once when plainhub_auth_status says "Not authenticated"', which implicitly excludes the already-authenticated case. It also states a negative rule for the parameter: 'Pass token only if the user gave it to you on their own' and 'Do not ask for it.'

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

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

No annotations are supplied, so the description carries the full burden, and it does disclose real behavior: the token is masked to prefix and trailing characters, and the reachable scope depends on token type. It stops short of saying what the response looks like when no token is saved (missing vs. invalid), which is the one behavior an agent would still want.

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 most decision-relevant fact (is a token saved, and how far it reaches) is front-loaded, and the secondary note about the token prefix is compact. The trailing 'Example: {}' is filler that could be dropped 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?

For a zero-parameter, no-output-schema probe, the description covers the key facts: what is inspected, how it is masked, what the two token classes imply, and when it is unnecessary. Only the no-token/empty result case is 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?

The tool takes no parameters, so the baseline is 4; there is nothing for the description to disambiguate. The 'Example: {}' fragment confirms the empty-argument call, though it adds little beyond the empty 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 ('Check whether a GitHub token is saved for PlainHub') and immediately scopes the answer by token type: fine-grained tokens reach only chosen repositories, classic/gh CLI tokens reach everything. That distinguishes it from the sibling plainhub_auth, which performs the auth rather than reporting 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?

It gives explicit routing: 'Use it before plainhub_auth to see whether the user is already set up', naming the alternative and the condition that selects it. It also states the negative case clearly - the ledger needs no PlainHub token, so posting, deciding and syncing do not require this check.

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 the outcome (a repository view with a file sidebar is opened), which is useful behavioral context beyond a bare name. However, it says nothing about whether authentication is required (notable given plainhub_auth/plainhub_auth_status siblings), what is returned, or what happens on an invalid repo.

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, front-loaded sentences with the purpose first and the routing rule second. The example line is slightly redundant with the schema's own example, which is the only waste.

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 single fully-documented required parameter, no output schema, and a clear statement of the resulting view make this largely self-sufficient. The missing piece is any note on authentication or failure behavior, which matters given the auth-related sibling tools.

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 repo parameter is already documented as owner/name format. The description repeats the same example in its 'Example' line, adding no meaning beyond the schema; 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 ('Open a GitHub repository in PlainHub with the file sidebar') and then distinguishes itself from the sibling that opens a single file. An agent can tell this apart from plainhub_open without inspecting 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?

Gives an explicit selection condition: use it when the user wants to browse a repository rather than open one file, which implicitly routes the alternative case to plainhub_open. No explicit exclusions regarding auth or permissions, but the core when-to-use guidance is 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 the full burden and does so: it discloses that the tool writes a local file only and does not sync, that it refuses on duplicate ids, that it returns a PlainHub link once pushed or remediation guidance if the repo is not on GitHub, and where the ledger lives (PLAINHUB_LEDGER env var). Those are non-obvious side effects and failure modes that cannot be inferred from 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?

Front-loaded with purpose, then when-to-use, then side effects and return behavior, then an example — a logical progression with little waste. The example is long, but it is the concrete payload shape an agent benefits from, so the length is mostly justified.

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

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

There is no output schema, yet the description explains the return value (a PlainHub link after push, or first-step guidance if the repo isn't on GitHub), plus the write-only local behavior and the required follow-up sync. Nothing essential to calling this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the worked example shows how id, summary, ref and body combine in a realistic card and illustrates the intended body structure (what changes / risk), adding value beyond the field descriptions. It goes slightly beyond the baseline rather than merely restating 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?

A specific verb-plus-resource: 'Raise a decision card for a person (status pending) in the ledger', plus the exact file location .agents/decisions/<id>.md. It is clearly distinguishable from siblings such as plainhub_ledger_sync (sharing) and plainhub_ledger_decisions (reading), so an agent can select it without opening another 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?

Explicit when-to-use with concrete triggers ('shipping a change, spending money or changing permissions'). It also states the crucial follow-up step ('run plainhub_ledger_sync to share it') and the condition under which it refuses (duplicate id), which is exactly the routing information an agent needs.

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 it does disclose the most security-relevant trait: the saved token is handed to https://app.plainhub.dev unless noAuth is true, revealing both the destination domain and a side effect. It also implies a browser-opening action rather than a pure data read. It leaves gaps around authentication requirements and failure behavior for an invalid SHA or repo.

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 purpose is front-loaded in the first clause, followed by usage context, a security note, and a compact example — no filler sentences. The JSON example is somewhat redundant with the schema but earns its place by showing a realistic combination.

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 four-parameter browser-handoff tool with no output schema and no annotations, the description covers purpose, timing, the token-handoff behavior, and an example. What remains unstated — auth prerequisites and error behavior — is modest 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?

Schema description coverage is 100%, so all four parameters are already documented, and the description only echoes them via an example object. The example illustrates that path filters to a single file, adding marginal meaning. Baseline 3 is appropriate since 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?

Names a specific verb and resource — showing what a commit changed in PlainHub's diff view — so the agent knows exactly what the tool produces. It is distinguishable from generic siblings like plainhub_open or plainhub_browse, though it never explicitly contrasts itself 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?

"Use it after a commit when the user wants to review the change in the browser" gives a clear trigger condition and makes the browser-review intent explicit. It stops short of stating when NOT to use it or naming a sibling (e.g. plainhub_open) as the alternative for non-diff browsing.

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 substantial work: it discloses ordering, the default filter, the on-disk source of the data, and a prompt-injection warning that results are wrapped in <ledger-data-…> markers and must be treated as data. It never explicitly says the operation is read-only, though 'List' strongly implies 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?

The scope, location, ordering, and returned fields are front-loaded in the first sentence, followed by usage, an example, and the safety note. Every sentence adds information an agent needs; nothing is 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 one-optional-parameter list tool with no output schema, the description covers location, ordering, default behavior, returned fields, and data-provenance safety. There is no meaningful gap an agent would need to guess at before calling it.

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 enum parameter is fully documented in the schema, so the baseline is 3. The description only reinforces the default ('pending') via the '{}' example and adds no new syntax or semantics 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?

The description names a specific verb and resource ('List decision cards in the ledger'), pins down the storage location (.agents/decisions/ via PLAINHUB_LEDGER), states ordering (oldest first), and enumerates the returned fields (id, status, waiting-since, summary). That is enough to separate it from siblings like plainhub_ledger_tasks or plainhub_ledger_thread without opening a 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?

It gives a clear use case ('see what is waiting for a person') and a concrete invocation example ('{} lists the pending cards'). It stops short of naming when-not-to-use or pointing at an alternative sibling, so it is clear context rather than 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 at all, the description carries the full burden and does well: it discloses the write target, that existing files are never overwritten, what is returned (a PlainHub link), and the fallback when the repo is not on GitHub. The only unmapped area is auth/credential requirements, which are presumably handled by plainhub_auth but are not referenced.

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 but front-loaded: purpose first, then artifacts, then constraints, then return value, then usage condition and example. Slightly overpacked into a single block, but every clause carries information that is not duplicated from structured fields.

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-param initialization tool with no output schema and no annotations, the description covers purpose, side effects, non-destructive guarantee, environment dependency, return value, error path, and sequencing relative to siblings. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description goes beyond it by showing the example {"language": "en"} and instructing the agent to use the language the user writes in, which is genuine selection guidance the schema's 'default en' does not supply.

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 ('Start a ledger') and immediately defines what that means concretely: creates .agents/room.md and .agents/schema.md in the repository set by PLAINHUB_LEDGER. This is clearly distinguishable from sibling tools like plainhub_post or plainhub_ledger_sync.

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 gives the when: 'Use it once, before the first plainhub_post, in a repository that has no .agents folder yet.' It names the sibling it must precede and states the negative precondition (no existing .agents), leaving nothing to inference.

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

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

With no annotations, the description carries the full burden and does well: it discloses the read-only nature, the environment-variable resolution of the root folder, path restrictions and no-link-following behavior, and that content is wrapped in <ledger-data-…> markers. It omits failure behavior for missing files and any size or encoding limits, 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?

Front-loaded with the action and target, followed by constraints, then usage and examples, then the safety note. No sentence is filler; the examples and the injection warning both earn their place in a compact block.

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 read tool with no output schema, the description covers where the file lives, what may be read, how to phrase the path, and what the return looks like (header + body, marker-wrapped). An agent has everything needed to call it correctly and interpret the result.

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: the path is relative to .agents and two concrete example paths show the threads/<slug>/<n>-<role>.md and decisions/<date>-<slug>.md conventions. That goes beyond the schema's single example.

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 ledger file) plus scope qualifiers: the repository folder from PLAINHUB_LEDGER, header and body included. It also distinguishes itself from the sibling ledger tools by positioning itself as the per-file reader for items those tools list.

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 it to read a whole message or decision card listed by the other ledger tools" gives a clear when-to-use rule and implicitly contrasts with the aggregate ledger siblings. It also states hard limits (only .md files inside .agents, links not followed) but does not name a specific alternative for cases like listing or searching.

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 supplied, so the description carries the full burden and does: it discloses the scoped commit (.agents only), pre-commit secret/header checks, rebase-then-push order, that the machine's Git login is used rather than the PlainHub token, and that it never pushes code. It also enumerates the three abort conditions (both-sides edits, unrelated uncommitted changes, unsent commits outside .agents), which is precisely the failure behavior an agent needs.

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 clause carries operational content and the mechanical sequence (commit → pull --rebase → push) is front-loaded before the when-to-use guidance. It is a dense run-on sentence, though, and would read faster split into purpose, sequence, and abort conditions.

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 mutation tool with no annotations and no output schema, the description covers the mechanism, credentials, scope limits, abort behavior, and ordering relative to siblings. Nothing an agent needs in order to invoke it safely is missing.

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

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

The tool takes zero parameters, so the baseline of 4 applies; the example invocation of {} reinforces that no arguments are expected. Nothing further could be added meaningfully.

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

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

The description names a specific verb and resource chain: share the ledger via Git by committing .agents changes, rebasing on others' changes, and pushing to the upstream branch. It is clearly distinguishable from siblings like plainhub_ledger_read or plainhub_ledger_init, which do not touch Git at all.

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 states exactly when to call it (after plainhub_post or plainhub_decide, before reading a thread another agent is writing) and names the sibling tools involved. Implicit alternatives (other ledger_* reads) are also clear from that scoping.

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: it discloses where the data comes from (the PLAINHUB_LEDGER directory, .agents/plan/), that entries are written by other agents or people, and that the result is wrapped in <ledger-data-…> markers and must be treated as data rather than instructions. It does not cover ordering, pagination or behaviour when the environment variable is unset.

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 plus a short example; the scope and data-provenance warning are front-loaded and nothing is redundant. The embedded JSON example is slightly awkward inline but still earns its 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 one-optional-parameter read tool with no output schema, the description supplies the data location, the returned fields, a usage cue and a prompt-injection safety note. Nothing material an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the sole parameter is already documented with examples (todo, doing, done) and a default of all. The description's inline example {"status": "todo"} adds only marginal clarity 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?

The description states a specific verb and resource ("List tasks in the ledger") and names the returned fields (file name, status, summary), which separates it from siblings like plainhub_ledger_decisions and plainhub_ledger_read. It stops short of explicitly contrasting itself with those siblings, so an agent still has to infer the boundary.

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 it to find work to pick up" gives a concrete intended use, but there is no guidance on when to prefer plainhub_ledger_decisions, plainhub_ledger_read or plainhub_ledger_thread, and no stated exclusions or 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 supplied, the description carries the full burden and does so: it discloses the storage location and env var dependency, the ordered field set of each message, and that results are wrapped in <ledger-data-…> markers with an explicit prompt-injection warning. That last point is behavioral context an agent could not get from any structured field.

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 usage, then alternative, then example, then the safety caveat — a sound ordering with no filler. The location/env-var detail is packed into a long opening sentence, which slightly blurs the lead.

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 read tool with no output schema, the description covers what to pass, when to call it, where data comes from, and roughly what comes back. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the mapping of the thread value into the path .agents/threads/<thread>/ and a concrete example call. The example value itself largely duplicates the schema's own example, which keeps this from a 5.

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 a work thread in the ledger') plus the physical location (.agents/threads/<thread>/) and the per-message fields returned. It also distinguishes itself from the sibling plainhub_ledger_read, which returns a full message rather than the thread listing.

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 ('Use it before you post to a thread, to see where the work is') and names the alternative tool with the condition that selects it ('Read a full message with plainhub_ledger_read'). No inference required from the agent.

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

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

With no annotations, the description carries the full burden and does add real behavioural context: the browser self-authenticates, the saved token is passed only when noAuth is false, the target URL defaults to app.plainhub.dev unless PLAINHUB_APP_URL is set, and the token is scoped to the production URL only. It does not state whether a browser window is opened as a side effect, whether the call blocks, or what happens on an invalid repo/path.

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 primary action is front-loaded in the first clause, with the settings mode, usage trigger, auth caveat, and example following in a logical order. The long parenthetical list of settings keys is dense and could read as schema duplication, but no sentence is purely 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 13-parameter, side-effecting tool with no annotations and no output schema, the description covers the two invocation modes, authentication handover, environment-driven URL, and a concrete example. What remains unstated is the observable outcome of the call (window opened, no return payload, or error behaviour for a bad repo).

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 genuine meaning beyond the schema: the settings parameters (theme, fontSize, preview, sidebar, lineNumbers, whitespace, header) only take effect when repo and path are omitted, a mode relationship the schema cannot express. The worked example further anchors repo/path/preview usage.

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 ("Open a file from a GitHub repository in the PlainHub browser editor") and explicitly identifies the overloaded second mode (editor settings when called without repo and path). The dual behaviour is disambiguated by the parameter condition, so an agent can distinguish it from siblings like plainhub_browse or plainhub_diff 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?

"Use it when the user wants to see or edit a file in the browser" gives a clear triggering context, and the parenthetical defines the settings-only invocation path. It does not contrast against sibling tools or state when not to use it (e.g., versus plainhub_browse for browsing repos), which keeps it 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?

With no annotations, the description carries the full load and does so: it discloses that only the local file is written, that sync is a separate step, that messages are never overwritten, and the exact rejection rules (secrets, summaries over 120 characters, bodies over 4KB). It even explains the return value and the degraded case when the repository is not on GitHub.

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 action and file location, then usage timing, then the sync caveat, then return value, then limits, then an example. Despite its length every sentence supplies a fact an agent needs to call this correctly; nothing is redundant padding.

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, and the description compensates by describing the returned link and the fallback message when the repo is not pushed. For a 6-parameter write tool with side effects and refusals, all decision-relevant information is present.

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 already 100%, so the baseline is 3, but the description adds real value on top: it restates the hard limits that govern body and summary, ties verdict/role to workflow moments ('reviewers post their verdict'), and closes with a complete worked example showing a valid combination of all required fields.

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 ('Add a message to a work thread in the ledger') and pins down where it lands (.agents/threads/<thread>/NN-<role>.md, next free number). That file-path detail cleanly separates it from ledger readers like plainhub_ledger_read and plainhub_ledger_thread.

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

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

Gives explicit trigger points: 'when you start (what you will do and what counts as done), after you commit, and when you finish; reviewers post their verdict.' It also routes the agent to the sibling that shares the file ('run plainhub_ledger_sync to share it'), so the write-vs-sync split is unambiguous.

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