Hydracept

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

Annotations already cover idempotency (idempotentHint=true) and safety (destructiveHint=false), but the description adds substantial context beyond them: the request may not stop upstream provider work, cost is not refunded, the call is safe to retry because terminal jobs report their state, bearer key is required, and the specific error codes. That is unusually rich disclosure for a mutation tool.

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

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

Front-loaded with purpose and the key usage constraint, and most sentences carry distinct information. However, the return values are stated twice ('Returns whether the request was accepted...' and 'Returns: Cancellation outcome envelope...'), which is mild 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?

Covers usage, caveats, auth, retry semantics, and error codes, and an output schema exists so return-shape explanation is not strictly required. The duplicated return description is the only thing keeping this from being fully tight, but 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?

Schema description coverage is 100% and the job_id description already includes the pointer to hydracept_jobs_find for unknown ids. The description adds no additional parameter-level meaning, 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 (cancel) and resource (one job), and explicitly bounds the scope by ruling out the near-miss interpretation ('stopping a local polling loop is not a cancellation'). An agent can distinguish this from siblings like hydracept_job_status or hydracept_submit_job without opening any 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 when-to-use condition ('only when the user explicitly asks to cancel the job itself') and a when-not ('stopping a local polling loop is not a cancellation'). This is exactly the routing guidance an agent needs to avoid mis-triggering on a stop-polling intent.

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

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

Annotations already cover readOnly/idempotent/non-destructive, so the bar is lower, yet the description still adds auth behavior (keyless vs bearer key), the key-overrides-query precedence rule, and concrete error semantics (NOT_FOUND, INVALID_ARGUMENT). This is meaningful context beyond the structured fields.

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 core purpose, then the sibling routing, then auth, then returns/errors in short declarative fragments. No filler sentences; the terse 'No charge. Read-only.' lines are informative.

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?

An output schema exists so return shape need not be expanded, and the description still summarizes the return (list vs single CapabilityDescriptor) plus error cases. For a 2-param read tool, nothing needed for correct invocation is missing.

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

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

Schema coverage is 100%, so the schema carries the field docs and baseline would be 3. The description adds the precedence rule (key wins, query ignored) and the INVALID_ARGUMENT consequence of conflicting query parameters, which goes slightly beyond what the schema states.

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

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

States specific verbs (browse, fetch) and the resource (capability descriptors, with keys/modes/schemas), and immediately distinguishes itself from the sibling hydracept_resolve_capability by intent-routing use case. An agent can tell the two apart 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?

Explicitly routes intent-only lookups to hydracept_resolve_capability, clarifies that list/resolve is keyless while a bearer key adds project-scoped fields, and notes no charge. Both the when and the alternative are named.

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 readOnly/idempotent/non-destructive annotations already covering the safety profile, the description adds real context beyond them: bearer key requirement, no charge on hosted, error conditions (WORKSPACE_KEY_REQUIRED, NOT_FOUND, DIRECTORY_CAPABILITY_DENIED), and the non-obvious side effect that stdio may write bytes to output_path. The mention of a local byte write sits in slight tension with readOnlyHint but is about local filesystem, not server state.

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 auth, cost, returns, and errors in a tight telegraphic style. Every clause carries signal, though the run-on single block is dense and slightly harder to scan than separated sentences.

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

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

Given annotations, an output schema, and 100% param coverage, the definition supplies the remaining essentials an agent needs: auth prerequisite, cost, error codes, and transport-dependent side effects. The only gap is that the referenced output_path is not reflected in the schema.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema, and the description adds little beyond it (the 'scopes the download URL' idea is already in schema). It references an output_path that does not appear in the input schema, which is more confusing than clarifying.

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: fetch artifact metadata (plus SHA-256 on hosted) for a succeeded job output. It distinguishes the metadata-read nature from siblings like job_status and get_receipt, though the mismatch between the tool name (download_artifact) and the 'read metadata' title leaves a slight ambiguity about whether bytes are returned or a file is fetched.

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

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

The precondition 'for a succeeded job output' implies when this applies, but there is no explicit when-to-use/when-not and no named alternative among siblings for obtaining artifact bytes vs metadata. Usage is inferable but not spelled out.

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

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

Annotations already cover the read-only, idempotent, non-destructive profile, but the description adds context they do not carry: no charge is incurred, a bearer key is required, and the two failure modes (WORKSPACE_KEY_REQUIRED, NOT_FOUND) are named. That is real behavioral disclosure beyond the structured hints.

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?

Six short clauses, front-loaded with identity and scope, then usage, then prerequisites, then return and error shape. No sentence is redundant and nothing is buried.

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 an output schema, this covers everything the agent needs: purpose, exclusions, sequencing against siblings, auth requirement, and error surface. Return-value explanation is technically redundant given the output schema but costs little.

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 job_id parameter is already fully documented in the schema (including the hosted-MCP requirement). The description's 'Hosted MCP accepts job_id only' largely restates that field description, so it meets the baseline without adding new syntax or format detail.

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 billing and provenance for a finished job') and immediately delimits scope with 'Does not run capabilities or spend money', separating it from hydracept_run and hydracept_quote_capability. The agent can distinguish this from every sibling 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?

Gives explicit when-to-use ('after terminal success') and an explicit alternative with its own trigger condition ('use hydracept_job_status while still running'). It also pre-empts the hosted-MCP parameter constraint and the bearer-key prerequisite.

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

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

Adds materially beyond the annotations: an auth requirement ('Requires bearer key'), a cost statement ('No charge'), a privacy constraint ('The list never includes prompt text'), and the error codes returned. These are exactly the operational facts the readOnly/idempotent hints do not 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?

Very short and front-loaded, with the core capability in the first clause. The telegraphic fragments ('intent is recent, failed, or reusable. Requires bearer key. No charge.') are efficient but slightly clipped in a way that reads more like field notes than prose.

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

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

Covers purpose, usage triggers, auth, cost, output shape, and failure modes. An output schema exists, so the return-value sentence is a bonus rather than a gap-filler, and nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so all four parameters are already documented. The description restates the intent values ('recent, failed, or reusable') without adding format or behavior beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource (find a prior job) plus the scope condition that separates it from siblings: 'when you do not have its id,' which implicitly contrasts with hydracept_job_status and hydracept_get_receipt. An agent can route here without opening any 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 three concrete triggers ('after context loss, for failure triage, or to recover a job to cancel') and the pre-condition of missing an id. It never names an alternative tool explicitly, so the routing 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?

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds meaningful context beyond annotations: bearer-key authentication, no charge, specific error codes, and return projection. It does not describe polling or terminal-state behavior, keeping it just below the top score.

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 sentences front-load purpose and usage, then add auth/cost and error details. Every sentence earns its place, with no filler or redundancy.

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

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

With an output schema covering return shape and rich annotations covering safety, the description completes the operational picture: when to call it, authentication, cost, and error conditions. Nothing essential is missing for a one-parameter read 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%, and the single parameter's schema description already states that the job id comes from hydracept_run or hydracept_submit_job. The description only repeats that job_id identifies the job, adding no format or handling detail beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('Read one job's current status') and explicitly distinguishes itself from hydracept_get_receipt, hydracept_jobs_find, and the submit/run flow. An agent can identify the correct 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?

Provides explicit sequencing: call after hydracept_submit_job or hydracept_run with wait=false, use hydracept_get_receipt after success, and use hydracept_jobs_find when the job id is unknown. Alternatives and conditions are fully specified.

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/idempotent/non-destructive, and the description adds substantial value beyond them: it does not execute, create a job, or charge the wallet, requires a bearer API key, and lists specific error codes including FundingRequired.

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 key non-execution guarantee before routing instructions, and each subsequent clause adds distinct value (auth, cost, return, errors). It is dense and slightly packed with parentheticals, but no sentence is wasted.

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

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

Even though an output schema exists, the description summarizes the return envelope (customerTotal, currency) and enumerates failure modes, covering everything an agent needs to call this 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 body, input, and capability_key are already documented in the schema (including the body/input alias caveat and the required-key note). The description adds no parameter-level meaning beyond that, so baseline 3 applies.

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

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

States a specific verb+resource: previewing the cost of a capability run. It explicitly disambiguates from execution siblings (hydracept_run, hydracept_submit_job) and from request_capability_quote on the full profile.

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 when-to-use (before spending, user asks about price) and when-not-to-use (run/submit_job are for execution), plus names a near-miss alternative (request_capability_quote) with the condition that distinguishes 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 already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description still adds real behavioral context beyond them: 'Keyless' (no auth needed), 'No charge' (billing), plus concrete error codes (INVALID_ARGUMENT for empty intent, UNAUTHORIZED for bad bearer). That is auth, cost and failure-mode disclosure that the structured fields do not 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?

Purpose is front-loaded in the first sentence, followed by routing, cost/auth flags, return shape and errors in dense fragments. Every clause earns its place, though the telegraphic fragment style ('Keyless. No charge. Read-only.') is slightly choppy rather than smoothly structured.

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

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

For a two-parameter resolver, the description covers purpose, routing, auth/cost, returns and error modes, and an output schema exists so return values need not be fully explained. Nothing an agent needs to select or 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 description coverage is 100%, so both parameters (intent, requirements) are already fully documented, establishing the baseline of 3. The description adds only the 'intent is empty' error case and otherwise restates what the schema provides, so it does not meaningfully exceed baseline.

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

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

States a specific verb ('Match') and resource ('capability key') with the modality ('natural language'). It explicitly distinguishes itself from the sibling hydracept_capabilities, so an agent can route between them 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 when-to-use ('use when the key is unknown') and a named alternative with its own selection condition ('use hydracept_capabilities when you already have a key or need the catalog'). This is exactly the when/when-not/alternative pattern.

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?

Goes well beyond annotations by disclosing payment settlement model (actual provider cost + fee, no minimum), auth requirement (bearer key), side effects (creates jobs, artifacts, provider usage), wait semantics, and enumerated error codes. Annotations only give the mutation safety profile; the description carries the real behavioral weight.

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 well organized: routing first, then wait semantics, then cost/auth, then returns and errors. Every sentence earns its place, though the error-code list is compact and slightly terse.

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

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

Given an output schema exists, the description still names return shapes, side effects, auth, cost, and failure modes, leaving nothing an agent needs before calling. Complete for a paid, side-effecting execution tool.

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

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

Schema coverage is 100%, so parameters are already documented. The description reinforces wait=true default and the invoke-vs-durable-job selection but adds little parameter detail beyond schema; baseline 3 is appropriate.

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

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

States a specific verb and resource ('Run a capability') and immediately distinguishes itself from siblings hydracept_quote_capability, hydracept_job_status, and hydracept_get_receipt via explicit 'not for' clauses. An agent can route correctly without opening any schema.

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

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

Explicitly names when to use (execution) and when not to (quotes, status, receipts), and routes the immediate-return case to hydracept_submit_job. Alternatives and their selecting conditions are all 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 declare it is a non-readonly, open-world, non-idempotent write, and the description adds context annotations cannot carry: it is paid, same billing as hydracept_run, requires a bearer key, and returns immediately rather than blocking. It does not address idempotency behavior despite the idempotentHint=false annotation and the idempotency_key parameter, which is a meaningful gap for a job-submission 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 core action and the routing rule before the housekeeping, and most clauses earn their place. The appended 'Returns:' sentence is largely redundant with the existing output schema, adding mild bloat to an otherwise tight definition.

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

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

Covers the non-blocking contract, auth requirement, billing, the downstream poll tool, and an enumerated error set (WORKSPACE_KEY_REQUIRED, FundingRequired, etc.). With an output schema present, return-value detail is optional, so nothing an agent needs to invoke 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 description coverage is 100%, so the baseline is 3; the description adds no per-parameter meaning (e.g. how capability_key resolves or when to supply idempotency_key) beyond what the schema already documents.

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

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

States a specific verb+resource ('Start a capability job') with the key behavioral trait ('return its id immediately'), and explicitly distinguishes itself from hydracept_run, hydracept_quote_capability, and hydracept_job_status. An agent can route without opening any 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 explicit when-to-use ('execution is required but this MCP call must not block'), when-not ('not for quotes or status checks'), and a named alternative with its selection condition ('Prefer hydracept_run when waiting is acceptable'), plus the follow-up tool to poll with.

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, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real value beyond them: auth requirements per transport ("Hosted requires bearer...; stdio checks local project binding"), the WORKSPACE_KEY_REQUIRED error condition, and the guarantee that no money is spent. Minor gap: no disclosure of latency or rate-limit behavior.

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

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

Front-loads the core purpose in the opening clause and each subsequent sentence carries distinct information (alternatives, side-effect guarantees, auth modes, error code). It is dense with semicolon-joined clauses and slightly run-on, but there is little 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?

An output schema exists, so return values need not be described, yet the description states the return scope anyway as light reinforcement. Auth requirements, error conditions, and negative scope are all covered, leaving only minor unexplored traits (e.g., behavior when refresh fails over the network).

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 refresh parameter is fully documented in the schema, including its stdio-only scope. The description adds nothing about parameter semantics beyond what the schema already provides, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ("Check workspace/session authentication and readiness, plus common setup errors") and explicitly scopes what it does not do ("Does not execute capabilities or spend money"). It also distinguishes itself from hydracept_job_status and hydracept_capabilities by name, so an agent can route 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?

Gives an explicit trigger ("Use when setup, auth, or project binding is in doubt"), names the sibling to use instead for executions ("use hydracept_job_status for a specific execution"), and rules out a near-neighbor ("Not a substitute for hydracept_capabilities"). When-to-use, when-not, and alternatives are all present.

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