CliDeck MCP — Network Knowledge

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

Annotations declare readOnlyHint=false, which would otherwise be puzzling for a read-style advisory tool; the description resolves this by disclosing that missing knowledge 'may create or update a tracked research demand' — a non-obvious side effect. It also asserts 'No device commands are executed', reinforcing the safety profile. No auth or rate-limit detail, but the key hidden side effect is surfaced.

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, zero filler, front-loaded with what is returned before the caveats. Each sentence carries distinct information: output, side effect, safety boundary.

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-value detail is unnecessary, and the side-effect and safety notes cover the behavioral gap left by annotations. Only the two optional parameters (enabled_features, operating_system) are left unexplained.

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

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

Schema description coverage is 0% across 5 parameters, so the description must compensate. 'Exact-model, exact-version' usefully signals that model/current_version/target_version are precise identifiers, but enabled_features and operating_system receive no mention at all, leaving half the parameter surface undocumented.

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 ('Return ... upgrade prerequisites, risks, checks, and rollback') scoped to 'exact-model, exact-version', and explicitly disclaims two things it does not do (no software download, no device commands). This separates it from device-facing siblings like analyze_device_snapshot and from generic lookups like query_network_knowledge.

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 by the resource (pre-upgrade planning for a specific model/version pair) but there is no explicit when-to-use statement or named alternative among the 18 siblings. An agent can infer intent but is not routed between this and query_network_knowledge/query_domain_knowledge.

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/idempotentHint/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond them: sensitive values are redacted in the output and input is not retained, which matters for handling production configs. It stops short of describing failure modes or size limits.

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 no filler; the core detection capability is front-loaded and the privacy guarantees follow immediately. 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?

An output schema exists, so return values need not be explained. However, for a tool with three parameters, two enums, and zero schema coverage, the description leaves the parameter surface and the meaning of 'bounded' unexplained, which an agent needs in order 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 0% across three parameters, so the description must compensate and largely does not. 'Redacting sensitive values' loosely gestures at redaction_profile and 'bounded CLI output' at snapshot, but neither snapshot_type's enum values nor the difference between 'secrets_only' and 'strict' is clarified.

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 ('Detect') and the exact extracted fields (vendor, model, OS, version) from a named input type ('bounded CLI output'). No sibling covers snapshot analysis, so differentiation is moot, but the purpose is unambiguous 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?

No when-to-use, when-not-to-use, or alternative guidance. It does not explain when to pick a snapshot_type other than 'auto', nor what qualifies as 'bounded' input or what happens if the input exceeds that bound. Usage is only inferable from the name.

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, idempotentHint, destructiveHint=false and closed-world, covering the safety profile. The description adds a genuinely useful extra trait ('without storing them'), signaling a stateless/non-persisting operation, and notes the graph is 'bounded', but says nothing about output shape or processing limits.

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

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

A single dense sentence that is front-loaded with the core action and scope, with no filler. Every clause (inputs, graph type, statelessness) contributes.

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 no explanation, and annotations carry the safety profile. However, for a tool with three 0%-covered parameters, the description leaves input wiring (source vs destination vs snapshot entries) unexplained, so it is only adequate.

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

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

Schema coverage is 0%, so the description must carry parameter meaning but does not. It names the four output types (mapping loosely to the output_type enum) but never explains source, destination, or the snapshots array structure and device_hint field, leaving the three parameters largely undocumented.

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: 'Build a bounded topology and packet-path graph', and names the input formats (CDP, LLDP, route, traceroute). It is clear what the tool produces, though it does not distinguish itself from the closely related sibling analyze_device_snapshot.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no alternative tools named. The requirement to 'supply' CDP/LLDP/route/traceroute outputs is the only implicit usage cue, which is thin given the many sibling analysis tools.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds a useful non-terminal constraint, but does not explain effects on the task, required permissions, or what happens after cancellation. It is consistent with the annotations and adds some value beyond them.

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

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

The description is a single, front-loaded sentence with no wasted words. It immediately states the action and scope, making it easy to scan and parse.

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?

Although annotations cover the safety profile and an output schema exists, the description is too thin for a destructive cancellation tool. It omits parameter guidance, access_token semantics, side effects, and post-cancellation behavior, leaving important context to inference.

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

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

Schema description coverage is 0%, and the description mentions no parameters at all. It does not explain the required task_id format or the role of access_token, so it fails to compensate for the missing schema descriptions despite having two parameters.

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

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

The description states a specific verb+resource combination: 'Cancel' an 'expert task.' It also adds the scope qualifier 'non-terminal,' which helps distinguish the operation from terminal-task handling. It does not explicitly differentiate itself from siblings like continue_expert_task or get_expert_task, but the action is clear.

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

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

The phrase 'non-terminal' gives an implied precondition for use, but the description does not state when to choose cancel versus alternatives such as continue_expert_task, get_expert_task, or request_expert_answer. Usage is inferable, but no explicit routing guidance is provided.

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=false, idempotent=false, destructive=false, and openWorld=false, so the safety profile is largely covered. The description adds only 'bounded,' which gestures at the 2000-char limit but says nothing about auth requirements (the access_token param), side effects, or what 'continue' actually mutates.

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?

It is a single front-loaded sentence with no wasted words, which is structurally clean. But it is under-specified rather than genuinely concise, so it earns only a middling score.

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 explained. Still, with three parameters at 0% coverage, no usage context, and a mutation-adjacent operation, the description is too thin for an agent to call it confidently.

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

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

Schema description coverage is 0%, so the description must carry the load, yet it names no parameters. 'Bounded additional input' loosely maps to the message maxLength, but task_id and access_token are entirely undocumented in both schema and description.

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 it provides additional input tied to a researcher, implying a continuation of an existing expert task. However, it never explicitly says it advances/continues an expert task session or how it differs from siblings like request_expert_answer or get_expert_task, so the purpose is only vaguely conveyed.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no named alternative. 'Requested by the researcher' faintly implies the trigger condition but leaves the agent to infer when this tool applies versus the other expert-task 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 declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered structurally. The description adds no behavioral context beyond that — nothing about what the returned 'contracts' mean, freshness, permissions, or error behavior for an unknown domain_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?

A single front-loaded sentence with no filler. It is efficient, though the terseness comes at the cost of the missing detail noted elsewhere.

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 spelled out, but the description still omits how to source domain_id and how this tool fits alongside the many sibling knowledge tools. For a tool whose only parameter is opaque, this is not enough.

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

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

Schema description coverage is 0% and the single required domain_id parameter has no prose explanation. The description does not state the expected slug format (only the schema pattern hints at it) nor that the id comes from list_knowledge_domains, so it fails to compensate for the coverage gap.

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 gives a verb ('Return') and a resource ('context and public-record contracts for one installed knowledge domain'), which is enough to understand it retrieves metadata about a single domain. However, 'context and public-record contracts' is jargon that does not clearly convey what is actually returned, and it never distinguishes itself from siblings like list_knowledge_domains or query_domain_knowledge.

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

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

There is no when-to-use guidance and no mention of alternatives. The agent is not told to call list_knowledge_domains first to obtain a domain_id, nor how this differs from query_domain_knowledge or get_knowledge_provenance.

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/idempotentHint/non-destructive, so safety is covered. The description usefully adds that this is a polling operation keyed by an access token, but it says nothing about rate limits, task lifecycle states, or what happens if the token is missing/expired.

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

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

A single tight sentence with the verb and lookup key front-loaded; nothing is wasted, though it is arguably under-specified rather than optimally concise.

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 no explanation, and both params are at least named. However, with 0% schema coverage the description leaves the access_token's role ambiguous (it is not a required field) and omits polling cadence/state guidance, leaving it only minimally adequate.

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

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

Schema description coverage is 0%, so the description carries the burden: it identifies both parameters conceptually (opaque ID and access token) but adds no format, token-purpose, or expiry detail beyond the pattern/minLength constraints visible in 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?

The description gives a specific verb ('Poll') and resource ('expert research task'), and the phrase 'by opaque ID and access token' clarifies the lookup mechanism. It does not explicitly differentiate itself from close siblings like continue_expert_task or cancel_expert_task, so it falls 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 word 'Poll' implies a repeated status-retrieval pattern, which hints at when to use this tool, but there is no explicit guidance on when to prefer it over continue_expert_task or cancel_expert_task, nor any stated 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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so safety is covered. The description adds useful context with 'safe source metadata' (implying filtered/redacted output) and the five-revision cap tied to 'active' revisions, but it doesn't say what happens when a ref is inactive or invalid.

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

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

A single tight sentence with the scope constraint front-loaded and no filler. Nothing superfluous, though it is arguably too terse to carry the semantic load given the 0% schema coverage.

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 needn't be described, and annotations cover the safety profile. Still, for a tool whose parameter is entirely undocumented, the description omits failure behavior for non-active or missing revisions, leaving an agent with unanswered edge-case questions.

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

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

Schema description coverage is 0% on the single required parameter, so the description must compensate. It only restates the maxItems constraint ('up to five') that the schema already enforces and hints that refs point at revisions; it never clarifies that refs are UUIDs or what constitutes a valid/active revision.

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?

Specific verb ('Return') plus resource ('source metadata for knowledge revisions') with a stated scope constraint ('up to five active'). It is reasonably distinguishable from siblings like query_domain_knowledge or describe_knowledge_domain, though it doesn't explicitly contrast 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?

No when-to-use guidance, no prerequisites, and no mention of an alternative tool. The only guidance is the implicit constraint that targets are 'active' revisions, which is a scoping detail rather than usage direction.

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, closed-world behavior, so the safety profile is covered. The description adds real value beyond that by explaining the asynchronous polling semantics and that 'Published' means the answer is complete. It does not mention other possible states (pending/failed) or error 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?

Two tight sentences, front-loaded with the core action and followed by the meaning of the returned status. 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?

An output schema exists, so return values need not be spelled out, yet the description still usefully interprets the 'Published' state. For a simple one-parameter polling tool this is nearly complete; listing the other possible status values would close the remaining gap.

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

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

Schema coverage is 0% – the single learning_id parameter has only a UUID pattern and no description. The description partially compensates by stating the parameter is an ID returned by a knowledge query or report_knowledge_gap, which is its most important semantic, but omits format/validity details.

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 – checking the status of a learning ID – and anchors it by naming where that ID originates (a knowledge query or report_knowledge_gap). That distinguishes it from the sibling query/report tools. It is clear, though it does not explicitly contrast with every other sibling.

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 context for use (after obtaining a learning ID from a knowledge query or report_knowledge_gap) and even the follow-up step ('repeat the original query to read it'). No explicit when-not guidance, but the async workflow is fully inferable.

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

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

Annotations declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=false, which already flags a non-read-only but non-destructive and repeatable call. The description adds genuinely new information beyond that: the write side effect is scoped to a 'tracked research demand', and 'No device commands are executed' rules out the most dangerous interpretation of a non-read-only network tool. It stops short of saying what the side effect does to the caller's state or how the demand is surfaced.

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 tight sentences, front-loaded with the core action and no filler. The middle sentence is slightly ambiguous about whether the research demand is a side effect of this call or a precondition, but nothing 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?

An output schema exists, so return-value detail is not required, and the description does cover the safety profile and the absence of device execution. However, for a tool with a nested context object and a state-mutating side effect, the total silence on all three inputs leaves the definition only minimally adequate.

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

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

Schema description coverage is 0% across three parameters, including a nested context object with six fields (model, vendor, version, runtime_mode, operating_system, shell_environment), and the description explains none of them. It never clarifies what 'limit' bounds (workflows returned? demand entries?) nor that 'context' is what tailors the workflow to a device environment. The description does not compensate for the coverage gap.

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

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

States a concrete verb and resource ('Return a deterministic, ordered workflow') and enumerates the workflow's content (safety, verification, rollback). It is distinguishable from siblings like review_network_change and verify_network_change, but never names or contrasts with any of them 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?

There is no statement of when to reach for this tool versus advise_network_upgrade, review_network_change, or resolve_network_context. The only situational hint ('Missing or incomplete knowledge may create or update a tracked research demand') describes a side effect, not a selection condition, so the agent must guess when this is the right call.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description adds only the scoping qualifiers 'installed' and 'compatible' and the fact that declared capabilities are included; with an output schema present, return format need not be restated. Modest added value over 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?

A single sentence with no filler, front-loading the verb and the resource. Every word earns its place.

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

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

For a zero-parameter, read-only listing tool with an output schema and complete annotations, the description covers what is needed to invoke it. The only gap is routing guidance against sibling knowledge tools, which is a usage matter rather than a completeness one.

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 per the baseline there is nothing for the description to compensate for. Schema coverage is reported at 100% and the empty object schema is self-explanatory.

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 (List) and resource (installed, compatible knowledge domain packs), plus what is returned (declared capabilities). It is clear what the tool does, but it does not explicitly contrast itself with the sibling describe_knowledge_domain, which is the obvious adjacent tool for domain detail.

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

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

No when-to-use guidance, no prerequisites, and no named alternative. The phrase 'installed, compatible' hints at scope, but an agent gets no instruction about when to call this versus describe_knowledge_domain or query_domain_knowledge.

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

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

Annotations declare readOnlyHint=false and idempotentHint=true, and the description explains why a 'query' can mutate: it 'may create or update a tracked research demand for missing or incomplete knowledge.' That side-effect disclosure is real value beyond the structured hints, though it doesn't cover latency, auth, or response shape.

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 the core action front-loaded and the notable side effect second; no filler. The second sentence's referent ('Network queries') is slightly murky, costing a point.

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 needn't be explained, and the write side effect is disclosed. However, with 4 parameters at 0% schema description coverage and a free-form nested context object, the definition leaves an agent guessing what to put in context or how limit constrains results.

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

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

Schema description coverage is 0% and the schema contains no per-parameter descriptions, so the description must carry the load. It only gestures at 'domain_id' (one domain) and 'context' (the pack's validated context); 'question' and 'limit' are never addressed, and the nested context object's expected keys remain opaque.

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 deterministic search in one domain') plus the mechanism ('that pack's validated context and public-record schema'). It implicitly contrasts with the network path, but never names the obvious sibling query_network_knowledge, so an agent must infer the split itself.

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

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

There is no explicit when-to-use, when-not, or alternative selection guidance. The phrase 'Network queries may...' gestures at a distinction but is ambiguous about whether it describes this tool's behavior or a different tool's, leaving routing 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?

Annotations declare readOnlyHint=false while the tool reads like a query, and the description usefully explains why: missing knowledge 'may create or update a tracked research demand,' justifying the write side effect. It also states 'No device commands are executed,' adding safety context. It does not mention rate limits or determinism caveats, but this is solid disclosure 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 tightly written sentences, front-loaded with the core purpose and followed by the side-effect and safety notes. Every sentence carries unique information with no 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?

An output schema exists, so return-value explanation is not required, and the side-effect behavior is covered. However, with 0% parameter coverage on a nested required context object and no differentiation from query_domain_knowledge, the definition leaves meaningful gaps for correct invocation.

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

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

Schema description coverage is 0% across 3 parameters, including a nested context object with vendor, version, model, runtime_mode (enum), operating_system, and shell_environment. The description only hints at version scoping and never explains the required question/context fields or how they map to results, so it fails to compensate for the coverage gap.

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 (Return) and resources (deterministic, version-scoped commands, diagnostics, concepts) tied to a network question, so purpose is clear. It does not distinguish itself from the close sibling query_domain_knowledge or describe_knowledge_domain, leaving the agent to infer the difference.

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 only implied: the agent can infer this answers network questions, and 'no device commands are executed' clarifies scope. There is no explicit when-to-use/when-not guidance or any pointer to sibling tools like query_domain_knowledge for a different knowledge scope.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so safety is partially covered. The description adds genuinely non-obvious behavior: the report is routed to priority research and 'Feedback alone does not change or quarantine published knowledge,' which sets correct expectations about side effects that annotations do not 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?

Three tight sentences with no filler, front-loaded with the core action. Efficient, though it spends a sentence on the caveat before clarifying the inputs it accepts.

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 explained, and the description covers purpose plus the key behavioral caveat. However, with 0% schema coverage and a nested context object plus a revision_refs array, the input side is under-specified for a tool of this complexity.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it largely does not. It loosely gestures at question/context/reason, but never explains the nested context object (model, vendor, version, runtime_mode, operating_system, shell_environment), the revision_refs UUID array, or length limits — a substantial gap for a 4-parameter tool with a nested object.

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 clear verb+resource: it records the original network question for priority research when an answer is incomplete or incorrect. An agent can tell what it produces, but it never distinguishes this from the sibling submit_feedback, leaving sibling selection ambiguous.

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 ('Provide missing context or explain why an answer was not useful') rather than explicit. No condition tells the agent when to choose this over submit_feedback or request_expert_answer, so routing between sibling feedback tools remains guesswork.

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 this is a non-read-only, non-idempotent, open-world operation, so the write/non-idempotent profile is covered. The description adds 'durable' (persistence beyond the call), which is genuinely useful, but it omits the task lifecycle (how the answer is retrieved) and never connects the non-idempotent hint to the idempotency_key parameter.

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

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

A single tight sentence with the action front-loaded and the condition following. No padding, though the brevity is partly what leaves parameters and lifecycle unexplained.

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 justifies skipping return-value description, but the tool takes a nested, entirely undocumented context object, and the description says nothing about the async task lifecycle or how the expert answer is later fetched via get_expert_task/continue_expert_task. An agent cannot call this confidently.

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

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

Schema description coverage is 0% across three parameters, including a nested context object with six undocumented sub-fields (model, vendor, runtime_mode enum, etc.). The description adds no meaning for question, context, or idempotency_key, so it fails to compensate for the coverage gap.

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 ('Create a durable research task') and frames it against 'deterministic knowledge', which implicitly distinguishes it from the query_* siblings. It stops short of naming any sibling directly, so differentiation is inferable rather than explicit.

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

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

Provides a clear triggering condition: use it 'when deterministic knowledge has no applicable answer'. That is real when-to-use guidance, but there is no explicit statement of when not to use it or which alternative tools (query_domain_knowledge, query_network_knowledge) should be tried first.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds no behavioral context beyond that — nothing about what resolution does, whether inputs are optional/partial, or how missing fields are handled — so it contributes little on top of 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?

A single front-loaded sentence with no filler, which is appropriately sized. Its brevity is efficient, though it is short because it omits necessary detail rather than because it is well-targeted.

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 needn't be explained, but with 6 parameters at 0% schema coverage and 0 required fields, the description leaves the agent unclear on what to supply and what happens with empty input. For this parameter complexity, the definition is under-specified.

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

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

Schema description coverage is 0% across 6 parameters, so the description carries the burden but only lists a subset (vendor, model, OS, version) without explaining formats, defaults, or valid values. It omits runtime_mode and shell_environment entirely and introduces 'portable software family,' which maps to no parameter, adding potential confusion rather than clarity.

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 the domain (vendor, model/platform, OS, version) but 'resolve ... context' is vague about the outcome — it never says what resolution produces or why an agent would call it. It largely echoes the input schema properties rather than stating a distinct verb+resource outcome, though it does separate the tool from analysis-oriented siblings.

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

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

There is no guidance on when to use this tool versus alternatives such as analyze_network_path or query_network_knowledge, nor any prerequisite or trigger conditions. The name implies a normalization/lookup step but the description provides no explicit when-to-use context.

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 annotations present, the description adds real value beyond them: it guarantees 'always returns available guidance and never executes a command' and discloses the side effect that missing knowledge 'may create or update a tracked research demand'. This explains why readOnlyHint=false despite no command execution, resolving an otherwise confusing annotation pairing. It does not cover rate limits or output shape, so not 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?

Three compact sentences with the core purpose front-loaded and no filler. The side-effect disclosure is appropriately placed last. Slightly dense but every sentence 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?

An output schema exists so return values need not be explained, and the behavioral disclosure is solid. But for a four-parameter tool with an undescribed nested context object, the absence of any guidance on how to populate intent/context/commands/config_diff leaves a real gap for correct invocation.

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

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

Schema description coverage is 0% across four parameters including a nested context object, so the description carries the full burden. It alludes to 'commands' and 'a configuration diff' (matching two params) but says nothing about the required 'intent' and 'context' fields or what belongs in the runtime_mode/model/vendor context, leaving half the parameters undocumented.

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 (review, advisory) and resource (commands or a configuration diff), making the operation concrete. It does not explicitly differentiate from the very similar sibling verify_network_change, so it falls short of a 5, but the 'advisory, non-executing' framing is distinguishable.

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 by 'advisory review of commands or a configuration diff' and 'never executes a command', which suggests pre-application review. However, it never states when to prefer this over verify_network_change or advise_network_upgrade, nor any prerequisites, leaving the agent to infer the routing.

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=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the write-but-not-destructive profile is covered. The description adds a genuine privacy constraint ('without including private logs'), which is useful beyond the annotations, but omits the access_token requirement, the consent requirement for sample_contribution, and any note about duplicate submissions.

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

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

A single tight sentence with the privacy constraint front-loaded alongside the category list. It is efficient, though for a 7-parameter write tool with a nested object it may be too terse to be sufficient.

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 7 parameters, a nested sample_contribution object, a consent gate, and an access token, the description is far too thin. An output schema exists so return values need not be explained, but the invocation prerequisites are 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 0% across 7 parameters, and the description only loosely covers the category enum and hints at sanitized payload privacy. rating, comment, task_id, access_token, revision_ref, and the nested consent/snapshot_type fields are left entirely to the schema with no semantic framing.

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 ('Submit') and resource ('feedback') and enumerates the feedback dimensions (correctness, freshness, safety, completeness). No sibling tool covers feedback submission, so differentiation is adequate, though it is not explicitly contrasted with any sibling.

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

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

There is no statement of when to use this tool versus alternatives, no indication of who should submit or in what situations, and no prerequisite guidance. The only constraint given is an implicit 'without private logs' prohibition.

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, idempotentHint and destructiveHint=false, so the safety profile is covered without the description's help. The description adds useful context that the evaluation is against a *signed* plan and a verification_token, but says nothing about what happens on mismatch, whether tokens expire, or how the verdict is reported. With annotations carrying the safety burden, this is adequate but thin.

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 sentence, zero filler, and the subject (the before/after evaluation) is front-loaded before the dependency clause. Nothing could be removed without losing meaning.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile. The main remaining gap is that an agent is not told what snapshots should contain or how failures surface, which matters for a 3-required-parameter tool with 0% schema documentation.

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

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

Schema coverage is 0%, so the description must compensate. It gives each parameter a semantic role: before/after snapshots are the compared outputs, and the verification_token is tied to the signed plan from review_network_change. However, it never specifies the expected format/content of the snapshots or what the token encodes, leaving format details undocumented.

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 (Evaluate) and precise resources (bounded before/after outputs, the signed verification plan) rather than restating the title. It also situates the tool in the workflow by naming review_network_change as the source of the plan, so an agent can distinguish the verifier from the reviewer 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?

The description provides clear operative context: this tool consumes the plan that review_network_change returns, implying it is used after that call. It does not state when not to use it or name any alternative verifier, so it falls short of explicit exclusions.

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