Nerdit

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

Goes well beyond the annotations: it discloses plan/limit constraints, the exact CNAME record to have the owner create, the Cloudflare DNS-only caveat, the pending state (awaiting_dns) that persists until the CNAME is observed, the 24-hour expires_at cleanup, and idempotent re-add behavior. Nothing here is recoverable from readOnlyHint/openWorldHint/destructiveHint alone.

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 before constraints, and every clause carries operational weight (plan, limit, record format, TTL). It is dense and somewhat run-on across multiple clauses, but there is no filler sentence to cut.

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 carries the return semantics itself (record.name and record.target, the CNAME shape) and the lifecycle states (awaiting_dns, expiry). An agent has everything needed to call it 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 description coverage is 100%, so the baseline is 3, but the description adds real constraint semantics for 'host' (must be a subdomain; bare domains are rejected) and clarifies that the record fields are returned for the caller to act on. It does not restate node_id/service_name, which the schema already covers.

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 an app domain', 'Serve one app at a subdomain') and immediately disambiguates the artifact the agent deals with, including a concrete example (app.example.com). It also names the sibling it hands off to (nerdit_check_domain), so it is distinguishable from the other domain 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 explicit prerequisites (needs the Pro plan, max 3 domains per account) and exclusions (bare domain such as example.com is refused), plus the required next step ('Once the record exists, call nerdit_check_domain'). The agent knows both when this tool applies and what to do after invoking it.

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

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

Annotations only say destructiveHint=true, openWorldHint=true, readOnlyHint=false; the description goes well beyond that with 'no rollback across services', the waiting_for_variables state and the rule that missing keys are supplied locally and never in chat, and the hosted-box sleep/wake semantics (services return one after another, an unready service is not broken). That is exactly the extra behavioral context annotations cannot carry.

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, but the body is a single unstructured block where operational rules (dry_run, waiting_for_variables, no rollback, consent) and the lengthy sleep/wake paragraph run together. The sleep/wake content is genuinely useful but would be far easier to scan as separate points.

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 explaining result states, and it does so for the key ones (waiting_for_variables, Applied-but-not-healthy, unready-after-wake). What a dry_run plan returns is not described, which is the main remaining gap for a destructive deploy tool.

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

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

Schema description coverage is 100%, so the schema already documents project_id, ref, repo_url, token_ref, dry_run and idempotency_key. The description reinforces a few points (immutable ID, machine consent, secrets never in chat) but adds no format, syntax, or interaction detail 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?

Opens with a specific verb+resource ('Apply an existing project by immutable ID with machine consent'), and the surrounding text clearly separates this deploy action from the read-side siblings get_project and diagnose_project. An agent can distinguish it from every other nerdit_* tool without opening the schema.

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

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

Gives concrete workflow guidance: start with dry_run=true, and after applying use get_project or diagnose_project to check health, with the explicit caveat that 'Applied means accepted, not healthy'. It also states the precondition that project-only consent cannot apply. It stops short of an explicit when-not-to-call rule, so 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?

Annotations already declare readOnlyHint/destructiveHint=false, yet the description adds genuinely non-obvious behavior: a hosted box sleeps, nothing inside runs while asleep (scheduled jobs, bots, queue workers, webhook receivers stop), it cannot be pinned on, and after a wake services return gradually for up to a couple of minutes so a not-ready service is not a failure. That retry/wake semantics is exactly the kind of context annotations cannot express.

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?

Purpose is front-loaded in the first sentence, then the sleep/wake caveat. The caveat paragraph is long but each clause carries operational consequence; it could be tightened slightly, but nothing is 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?

For a dispatcher tool with an open-ended nested arguments object and no output schema, the description supplies the missing workflow context: docs URL for machine tools, discovery via nerdit_list_tools, and latency/retry expectations. Error handling of the wrapped tool is the main thing left unstated.

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

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

Schema description coverage is 100%, so node_id, tool_name and the nested arguments object are already documented in the schema. The description adds no format or constraint detail beyond what the schema provides, which is the baseline-3 case when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Call one machine MCP tool that only reads... on one selected Nerdit node'), and the read-only qualifier cleanly separates it from the sibling nerdit_call_write_tool without needing either schema opened.

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 read-only framing plus the pointer to nerdit_list_tools ('Name of a tool from nerdit_list_tools on this node') tells the agent the workflow precondition. It stops short of explicitly naming nerdit_call_write_tool as the alternative for mutating calls, so the contrast is implied rather than stated.

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

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

The description adds substantial behavior beyond the annotations: the hosted box sleeps after inactivity, wakes on the next call, services recover sequentially over a couple of minutes, and sleeping stops scheduled jobs, bots, queue workers and webhook receivers. It also warns that a not-yet-ready service is not broken and should be retried.

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 front-loaded with the core purpose and then moves into operational caveats. It is longer than a minimal description, but the wake/sleep behavior is material and most sentences earn their 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 destructive, open-world tool with no output schema and a nested arguments object, the description provides the behavioral context an agent needs: what it may change, how to use next_step tools, and how to handle sleeping/waking delays.

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 node_id, tool_name and arguments are already fully documented in the schema. The description does not add parameter-specific semantics beyond what the schema provides, which is acceptable given the complete coverage.

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 ('Call') and resource ('one machine MCP tool... on one selected Nerdit node') and gives examples of mutation types (deploy, stop, write files, set secrets). It also distinguishes itself from the read-tool sibling by explaining that read-only machine tools are accepted only to support next_step calls.

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 explains the intended context clearly: call a write-capable machine tool on a selected node, and optionally use it for read-only next_step tools. However, it does not explicitly say when to prefer the sibling nerdit_call_read_tool, leaving a small routing ambiguity.

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 destructiveHint=true and readOnlyHint=false, yet the description frames the tool purely as a lookup that 'return[s] its status' and never explains any mutation, side effect, or reason a check would be destructive. The status definitions explain what the results mean, but the tool's actual behavioral risk profile is left undisclosed and unreconciled with its annotations. No explicit safety claim is contradicted, so this is a transparency gap rather than a hard contradiction.

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

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

The core action is front-loaded in the first clause, followed by invocation timing and then a compact status glossary. It is dense and slightly run-on, but every clause carries information an agent needs; nothing is 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?

There is no output schema, so the enumeration of awaiting_dns/pending/active/error return states is a genuinely valuable addition that the structured fields do not provide. For a 3-parameter tool with fully documented parameters, little else is missing besides an explanation of the destructive annotation.

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%: host, node_id, and service_name are each documented in the schema, including that node_id comes from nerdit_list_nodes. The description adds no parameter-level detail beyond that (no format or linkage notes), so the schema does the heavy lifting and 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 set: it looks up one domain's CNAME and certificate and returns status, and the 'one domain' scope separates it from the list-style sibling nerdit_list_domains. It never names a sibling or explicitly contrasts with nerdit_add_domain/nerdit_remove_domain, so an agent must infer the routing. Clear, but not sibling-differentiating.

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?

Timing is explicit: 'Call it after the owner created the record, and again later while the status is pending (DNS changes can take a while to reach us).' That tells the agent both when to invoke it and that repeated polling is expected. No when-not-to-use guidance or named alternatives are given, 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 cover the safety profile (readOnly, non-destructive, closed-world), and the description adds real context beyond them: the authorization requirement that the daemon token must own the service, and the fact that log output is bounded rather than complete. Returned components are also listed, which helps set expectations.

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 with no filler. The action and scope come first, followed by the auth prerequisite — every clause earns its place.

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

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

With no output schema, the description usefully enumerates what a diagnosis returns (deploy phase, health, logs, remediation) and states the auth precondition. Remaining minor gap is any hint about cost or depth of the log bundling relative to log_tail.

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

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

Schema description coverage is 100%, so the schema already documents service, log_tail, and project_id fully. The description reinforces that the ID is immutable and that diagnosis targets a single service, but adds no format or constraint detail 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 (diagnose), a tightly scoped resource (one service within a project), and enumerates the payload (deploy phase, health, bounded logs, remediation). It does not explicitly differentiate itself from the overlapping sibling nerdit_project_logs, so it stops 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?

Usage is implied — you call it to assess the health of a service — and it states the prerequisite that the daemon token must own the service. But it names no alternatives (e.g. when to prefer nerdit_project_logs or nerdit_get_project) and gives no when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real value beyond that by disclosing the consent requirement ('project consent or consent for its current home machine'), which an agent must satisfy before calling. It does not describe return shape or any freshness/live-state caveats.

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 no filler; the read scope comes first and the operational guidance (when to call, auth prerequisite) follows. Every clause carries information an agent needs.

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 parameter, no output schema and safety already covered by annotations, the description supplies the missing pieces: what data is returned (services, resources, addresses, variable names), the usage window (before apply/diagnose) and the consent prerequisite. Nothing material is left for the agent to guess.

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

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

Schema description coverage is 100% and the single parameter is fully documented in the schema, including the pattern and the instruction to use the ID from nerdit_list_projects rather than a name or slug. The description's 'by immutable project ID' merely reinforces the schema, so baseline 3 applies.

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

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

States a specific verb (read) and resource (live services, resources, addresses, variable names) scoped by an immutable project ID. It also implicitly separates itself from nerdit_list_projects (name/slug listing) and nerdit_apply_project / nerdit_diagnose_project by positioning the read as the precursor to those actions.

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?

'Read before applying or diagnosing' gives a clear context for invocation and effectively names the sibling actions it precedes. It stops short of explicit exclusions or naming a literal alternative tool for other read needs, so it is strong context rather than full when/when-not guidance.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, idempotentHint=false; the description adds substantial context the annotations cannot convey: the 50-rule cap, group-count-as-one, that re-adding a rule returns the existing one, that invite emails are re-sent and count toward the owner's daily invitations, and that an unshared app becomes private and locked to its hosted address. The one weakness is it never spells out the destructive/lock side effect in annotation-matching terms, but the coverage is well above average.

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 paragraph that front-loads what the tool does and then walks through each kind in order of importance, with no wasted sentences. It is information-heavy but each clause carries a constraint, limit, or side effect.

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 5-parameter mutation tool with no output schema, the description covers prerequisites, per-kind semantics, idempotency behavior, rate/quota limits, and side effects. Return values are not described, but the tool's state changes and the re-add behavior are, leaving little an agent needs to call 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 coverage is 100%, so the baseline is 3; the description nonetheless adds meaning beyond the schema, explaining the real-world consequence of each kind, that value for group must come from nerdit_list_access_groups, and that invite only applies to kind email and consumes daily invitation quota.

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 precise verb and resource (grant app access) and enumerates the three grantable principals (email, Workspace domain, owner group) with distinct behaviors for each. It also distinguishes group handling by pointing to nerdit_list_access_groups for group ids.

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 situational guidance: confirm the exact domain with the owner before using google_domain, public mail providers are refused, groups can only be created/changed in the Nerdit console, and the Pro plan plus an online machine are prerequisites. It does not explicitly contrast with sibling nerdit_revoke_app_access or nerdit_list_app_access, which is the only gap.

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

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

Annotations already declare readOnly, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely useful context beyond them: the immutability of groups via this API and the fact that each result reports a member count.

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 resource and return shape, followed by the downstream use and the hard constraint. Every clause carries information and none is redundant with the schema or annotations.

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

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

There is no output schema, so the description correctly supplies the return shape (id, name, member count), the purpose, and the restriction that mutation happens elsewhere. For a zero-parameter read tool with no output schema, nothing an agent needs to call it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. No misleading parameter claims are made.

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

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

States a specific verb and resource (list the owner's access groups) and enumerates the returned fields (id, name, people count), which separates it in content from sibling nerdit_list_app_access. It stops short of naming the sibling it differs from, so an agent must infer the distinction from the resource wording.

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

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

Explicitly routes the agent downstream ("Use a group id with nerdit_grant_app_access kind group") and states a when-not: groups cannot be created or changed here, only in the console. This is clear context with a real constraint, though it does not contrast against the other listing siblings.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds genuinely new behavior: results are still produced when the machine is offline, and lock is null in that case, when no rule exists, or on a public app. It also explains that group rules carry group_name and group_people alongside the group id.

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, then a compact block of edge-case semantics. Dense but each clause carries information; the long middle sentence could be split but nothing is 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?

With no output schema, the description carries the return-value burden and does so well, describing the rule fields and the null-lock cases. The remaining gap is that it does not mention ordering or result size for a machine with many rules.

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

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

Schema description coverage is 100% and both parameters (node_id, service_name) are documented in the schema, including the pointer to nerdit_list_nodes. The description adds only the framing that the app must be private, so the baseline of 3 is appropriate.

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

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

States a precise verb and resource: list the access rules granting non-owner access to one private app, and enumerates the returned fields (id, kind, value, live sessions, lock). This cleanly distinguishes it from the mutating siblings nerdit_grant_app_access and nerdit_revoke_app_access.

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 context of use is clear from the opening clause, and it usefully notes the offline case ('Works while the machine is offline; lock is then unknown'), which tells the agent when results are partial. It never names an alternative tool or an explicit when-not-to-use condition, 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 establish the safe read-only, closed-world profile, but the description adds genuinely new behavioral context: a full breakdown of the four status states and what each means operationally, plus the notable claim that it "works while the machine is offline." This is well beyond what the structured fields convey.

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

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

Front-loaded with the primary action and return contents, then a compact inline definition list of statuses. Dense but nearly every clause carries information; the run-on status enumeration is the only minor readability cost.

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 return values and does so adequately (host, status, record type/name/target, expires_at) plus status semantics. It omits pagination/empty-state and error behavior, which are minor gaps for this scope.

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 node_id even cross-references nerdit_list_nodes, so the parameters are already fully documented. The description adds only the framing that the domains belong to a single app; baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ("List the domains of one app") and goes further to enumerate exactly what is returned (host, status, DNS record, expires_at). This clearly separates it from siblings like nerdit_add_domain, nerdit_remove_domain, and nerdit_check_domain.

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 through the status lifecycle and the "until verified" framing, which orients the agent to domain-verification workflows. However, it never explicitly says when to prefer this over nerdit_check_domain or nerdit_list_app_access, so the guidance remains implied rather than stated.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), yet the description adds genuinely non-obvious operational behavior: nodes sleep, nothing inside them runs while asleep, they cannot be pinned on, and services return progressively for up to a couple of minutes after a wake. That is real context beyond the structured fields. It does not describe what a returned node record contains or whether stopped/sleeping machines still appear in the 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?

Purpose is front-loaded in the first short sentence, with the sleep/wake caveats following as supporting detail. The second sentence is long and clause-heavy, packing sleep behavior, wake timing and retry advice into one run-on, but every clause carries operationally useful information rather than 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 zero-parameter read tool with no output schema, the description covers the failure modes an agent will actually hit (sleeping nodes, staggered service startup, needing to re-call). The remaining gap is that it never says what the listing looks like or what 'selected for this connection' means, which an agent must infer after the call.

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 (empty schema, additionalProperties false, 100% coverage), so there is nothing for the description to disambiguate. Baseline 4 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?

'List the active Nerdit nodes selected for this connection' gives a specific verb (list) plus resource (nodes/machines) and scopes it to the current connection, which cleanly separates it from siblings like nerdit_list_projects, nerdit_list_domains and nerdit_list_tools. It never explicitly names a sibling or contrasts itself with one, so it stops short of a 5.

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

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

The description implies when the tool is relevant (to see which machines are attached to this connection) and gives retry guidance for a waking box ('wait and call again'), but it never states when to prefer this over adjacent inventory tools such as list_projects or list_tools. Usage has to be inferred from the resource noun.

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/destructiveHint=false, and the description adds substantial context beyond them: cursor-paginated last-known snapshots, propagation delay of up to ~a minute for new projects, the 5 s retry path, default consent behavior for new projects, and the hosted-box sleep/wake semantics including that sleeping stops scheduled jobs, bots, queue workers and webhook receivers and cannot be prevented.

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?

Purpose and sibling routing are correctly front-loaded in the first two sentences, but the trailing block on hosted-box sleep/wake and service warm-up is long and only indirectly relevant to listing projects. It is readable and information-dense rather than padded, but it is not tight.

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 read-only, no-required-param list tool with full schema coverage and no output schema, the description covers pagination, latency/sync expectations, routing to the live-detail sibling, consent behavior and infra wake semantics. Nothing an agent needs to call it correctly or interpret a stale/missing result 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% and both parameters are documented in the schema, so the baseline is 3. The description says 'cursor-paginated' and implies the cursor encodes last-known snapshot ordering, but adds no format or usage detail beyond what limit/cursor already document.

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

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

States a specific verb and resource (list/discover projects) plus the scope covered: explicitly granted projects and projects on selected machines, including private and empty ones. It also explicitly separates itself from nerdit_get_project, so an agent can route without opening either schema.

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

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

Names the alternative (nerdit_get_project) and the condition that selects it (need live runtime details), and explains the sync-visibility tradeoff between the two. It gives no explicit 'when not to use' guidance relative to the other list_* siblings, so it falls just 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 declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds the filtering semantics of compact/prefix/name, but says nothing about result size, pagination, or node-access prerequisites; a 3 reflects useful but modest added context over 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?

Front-loaded with the purpose, then a single sentence covering the three optional selectors. It is compact and each clause earns its place, with only mild redundancy against the schema text.

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 read-only list tool with no output schema, the description plus the schema's compact-mode shape description tell the agent what it gets back. The only gap is that it does not warn about large result sets or how to narrow them, but the prefix/name/compact options largely cover discovery needs.

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 (including node_id) are already documented in detail in the schema. The description restates compact, prefix, and name behavior but adds no format, syntax, or edge-case detail beyond it, so the baseline of 3 applies.

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

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

The first sentence states a specific verb (list) and resource (MCP tools exposed by a selected Nerdit node), which is distinct from the other list_* siblings that target domains, nodes, projects, and access groups. An agent can tell what this returns 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?

The description gives clear operational context: use 'name' to fetch exactly one tool's full definition and 'compact' for summaries, which implicitly frames how to navigate the tool catalog before invoking nerdit_call_read_tool/nerdit_call_write_tool. It stops short of naming those siblings or stating explicit when-not-to-use conditions, so it is clear but not fully routing-aware.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description's only added behavioral claim is 'bounded', which hints at truncation/limits but never says what the bound is, whether results are paginated, or what happens with no matches. Adequate, but it adds little 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?

Two sentences, zero padding, with the scoping constraint front-loaded before the alternative-tool pointer. Every clause earns its place.

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

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

For a read-only, single-purpose log reader with no output schema and full schema coverage, the description plus annotations give an agent what it needs to call the tool. It is slightly thin on what the returned log window looks like (e.g., default tail of 100, build vs runtime source semantics), though those live in the schema defaults.

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

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

Schema description coverage is 100%, so every parameter (grep, tail, since, source, service, project_id) is already documented in the schema, including the 'never its name or slug' rule. The description only restates the project-ID immutability and single-service scoping, adding no new syntax or semantics. Baseline 3 is correct.

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

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

States a specific verb and resource ('Read bounded logs'), plus the scope constraints ('one service within a project', selected by immutable project ID). It also names the sibling it is not (nerdit_diagnose_project), so an agent can route without opening either schema.

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

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

Gives an explicit alternative for a concrete scenario: 'Use nerdit_diagnose_project when a deployment fails.' However it offers no guidance on when NOT to use this tool, and no prerequisites (e.g., which ID to supply, whether the project must be running) beyond what the schema already states.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so safety is covered. The description adds genuine extra context beyond that: the removal is immediate ("at once") and the owner's DNS record is deliberately left in place rather than cleaned up. The one gap is that it doesn't say whether the caller needs ownership of the node or app.

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

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

Two tight sentences with zero filler; the primary effect is front-loaded and the DNS caveat follows. Nothing needs trimming.

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 three-param destructive tool with no output schema, the description plus annotations cover effect, timing, and side effects. Authorization requirements and any error cases (e.g., domain not currently assigned) are the only missing pieces.

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 three parameters (host, node_id, service_name) are already documented, including the cross-reference to nerdit_list_nodes. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource — stop serving an app at a domain — and adds the effect of freeing a slot, which implies a quota. It is clearly the inverse of the sibling nerdit_add_domain, though it doesn't name that sibling explicitly.

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

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

The description explains what happens but gives no when-to-use guidance, no prerequisites (e.g., the domain must currently be assigned), and no reference to alternatives such as nerdit_list_domains or nerdit_check_domain. The agent must infer usage from context alone.

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 destructiveHint=true and idempotentHint=true, and the description earns credit by explaining what the destruction actually is (visitors' sessions are terminated) and what idempotence looks like in practice (a rule_id that is not one of this app's rules changes nothing and returns the same answer). It also adds the unusual operational fact that the call works while the machine is offline. 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?

Three sentences, front-loaded with the action and its side effect, then provenance, then edge-case behavior. Slightly repetitive in restating the confirm-with-nerdit_list_app_access idea twice, but 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 destructive mutation with no output schema, the description covers side effects, no-op semantics, and offline operability, which is most of what an agent needs. It omits permission/auth requirements and what happens when the last access rule is removed, which are minor remaining gaps.

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, but the description adds meaning not in the schema: rule_id must belong to this specific app, and a mismatched rule_id is a silent no-op rather than an error. It adds nothing new for node_id or service_name, which the schema already documents with provenance.

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 precise verb and resource – remove one access rule of this app – and adds the non-obvious consequence that visitors' sessions end simultaneously. It also names nerdit_list_app_access as the source of rule_id, which cleanly separates it from the sibling enumeration tool.

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 tells the agent where to obtain rule_id (nerdit_list_app_access) and how to verify a successful revoke. It never explicitly names nerdit_grant_app_access as the inverse operation or states when not to revoke, but the grant/revoke pairing is unambiguous from the tool names.

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 flag destructiveHint=true and idempotentHint=true, but the description adds the non-obvious hazard that values enter the agent transcript even when secret=true, and that only names are returned. It also discloses operational behavior (services pick up values on restart/redeploy), which annotations cannot express.

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

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

Four short clauses, all earning their place, with the critical transcript-leak warning front-loaded after the core purpose. Slight redundancy with the schema's own 'never send credentials' note, but the repetition is defensible for a safety-critical warning.

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 stating the return value ('names only'). For a destructive, nested-object write tool it covers purpose, safety hazard, credential workaround, scoping, and propagation — everything needed to call 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 100%, so project_id, values, secret, service, and idempotency_key are all documented in the schema itself. The description reinforces the immutability constraint on project_id but adds no format or syntax detail beyond what the schema already provides; 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 ('Set variables on an existing project') plus a scoping constraint (by immutable ID) and return format (names only). It cannot be confused with any sibling such as nerdit_get_project or nerdit_apply_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 an explicit when-not: credentials should be set by the human via `nerdit vars set <project> --secret --prompt KEY` instead of this tool. It also states the propagation timing (next restart or redeploy) and the local-ownership constraint, 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.