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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered; the description adds genuinely new behavioral context about gateway-enforced plan, tenant policy, token allowance and usage metering, plus the fact that output is generated text. It stops short of describing error behavior or latency/streaming.

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: routing rule first, then return value, then policy/metering constraints. Every sentence carries distinct information and nothing is repeated from the schema or annotations.

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

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

With no output schema, the description does state the return type ('generated text'), and all five parameters are fully documented in the schema while annotations cover the safety profile. Nothing critical is missing, though a hint about model-tier selection trade-offs would round it out.

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

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

Schema description coverage is 100% and both enums are documented inline, so the schema carries the parameter burden. The description only alludes to 'domain and model tier' without adding syntax, constraints, or tier trade-offs beyond what the schema already states – baseline 3.

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 the resource (general or specialist questions) and the output (generated text from the selected domain and model tier), so the agent knows this is the general-purpose chat/completion endpoint. It distinguishes itself from siblings by positioning as the fallback when no more specific Bee tool fits, though it never names those 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?

'Use for general or specialist questions that do not require a more specific Bee tool' gives a clear when-to-use condition and a category-level when-not. The weakness is that the alternatives (bee_code, bee_security, bee_research) exist in the sibling list but are never named, leaving the agent to infer the routing itself.

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, open-world), so the bar is lower, yet the description adds genuinely new context: the return surface ('text and proposed code') and the hard boundary that it does not touch files, execute commands, or mutate a repo. It omits auth, rate-limit, or latency details, but those are peripheral here.

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

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

Two dense sentences: the first front-loads the capabilities, the second covers output and scope limits. No filler, and the most decision-relevant information (what it does and does not touch) comes first.

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

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

There is no output schema, so the description carries the return-value burden and discharges it ('returns text and proposed code'). Combined with the scope limits and action selection, an agent has enough to invoke it correctly; only finer detail like handling of very large files is absent.

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?

With 100% schema description coverage, the schema already documents every parameter including the action enum and its per-action params (error, focus, framework), so a 3 baseline is appropriate. The description only adds the meta-instruction to select an operation via 'action', which is minor incremental value.

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 (explain, fix, refactor, generate tests) and a clear resource (code), making the tool's remit obvious at a glance. However, it never names the most likely alternative sibling (bee_chat) to distinguish a code-focused request from a general chat turn, so sibling differentiation is only implicit.

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

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

'Use for code explanation, bug fixing, refactoring, or test generation' gives clear triggering contexts, and the negative clause ('does not read files, execute commands, or modify a repository') usefully bounds usage. There is no explicit when-not or named alternative, so it stops short of full routing guidance.

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

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

Annotations declare non-read-only, open-world, idempotent, non-destructive, but the description adds the material preconditions (verified host runtime, explicit capability evidence) and disclaims side effects an agent might otherwise assume (no screen observation, no input control, no local driver). What it does not disclose is what a successful validation produces or whether the gateway records anything.

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

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

Two sentences, front-loaded with the action and followed by the scope negation; nothing is padded. Slightly abstract phrasing ('at the hosted gateway') costs a little precision but does not waste space.

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

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

For a two-parameter nested-object tool with no output schema, the description should say what a validation call returns or what state it leaves behind, especially since readOnlyHint=false implies possible side effects. Preconditions are covered, but the outcome half 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 (host report, optional action request) are already documented in the schema, including the bee.computer.v1 protocol and approval evidence. The description adds no syntax, format, or field-level meaning beyond that, 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 (validate) and resource (Bee computer-use host capability report plus optional governed action request) at the hosted gateway. The negative clause ('does not observe a screen, control input, automate a device, or create a local driver') sharpens what the tool is NOT, which is valuable given how easily a computer-use tool is confused with device automation, though no sibling is named.

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

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

Gives clear context for invocation: the report must be real, the request governed, and execution must happen in a verified host runtime with explicit capability evidence. It stops short of naming an alternative tool or stating when NOT to call it, so it sits at 'clear context, no exclusions'.

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, openWorld=true. The description adds genuinely new behavioral context beyond those: it 'consumes the plan's document allowance' (cost/quota side effect) and warns that it does not read local files, setting a boundary on what the tool will not do.

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 front-loaded sentences with zero waste: usage condition first, then side effects and the local-file boundary. Every clause earns its place.

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

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

For a 2-param tool with no output schema and full annotation coverage, the description covers purpose, trigger, cost, and a key limitation. It leaves return behavior (e.g., document id) and duplicate-handling implicit, but those are minor against the annotated contract.

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 'content' and 'source' are already documented in the schema. The description only gestures at 'supplied text' for content and adds no format, length, or source-label semantics. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

Specific verb+resource: 'persist supplied text' and 'Creates a searchable document' in the 'authenticated tenant's hosted Bee knowledge base'. An agent can distinguish this ingestion/write action from sibling reads like bee_documents_search 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?

'Use only when the user intends to persist supplied text' gives a clear triggering condition, and 'it does not read local files by itself' draws a useful when-not boundary. However, it never names the obvious alternative (bee_documents_search) to route retrieval-vs-ingestion intent explicitly.

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

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

Annotations already establish readOnly, idempotent, non-destructive and open-world behavior, so the bar is lower. The description nonetheless adds real context beyond the annotations: the ranked-chunk return shape, the entitlement prerequisite (RAG-entitled plan), and the guarantee that the library is not modified.

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 packed sentences: the first states the action and scope, the second the return shape and the entitlement requirement. Nothing is repeated and the most important information leads.

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 search tool with no output schema, the description covers action, return shape, safety posture and the plan prerequisite. It stops short of noting anything about ranking behavior or result limits, but the essential call-time information is present.

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

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

Schema description coverage is 100%, with both 'query' and 'k' documented inline ('What to search for', 'How many chunks to return'). The description adds no syntax, format, or tuning guidance beyond that, 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 (retrieve excerpts) and resource (hosted Bee document library), plus the scope of the return (ranked chunks and source labels). It is easily distinguishable from bee_documents_add, though it does not explicitly contrast with the nearby bee_memory_search 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?

The opening 'Use to retrieve...' frames the intended use and adds a precondition (RAG-entitled plan), which is helpful. However, it names no alternative tool or when-not condition, so an agent must infer whether to pick this over bee_memory_search or bee_research.

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

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

Annotations already flag this as a non-readonly, non-idempotent, open-world write. The description adds genuinely useful context beyond that: writes are scoped to the authenticated user, gated by opt-in and tenant policy, and near-duplicates are auto-suppressed. It does not describe the response or failure modes (e.g. policy rejection), leaving a small gap.

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 that front-loads the when-to-use gating and then packs in behavior. No filler, nothing redundant with the schema or title.

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 mutation tool with no output schema, the description covers intent, target, auth scope, policy gating, and dedup behavior, which is nearly everything an agent needs. It omits what the call returns and whether the suppression is reported, a minor but real 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 description coverage is 100% for both parameters, including the kind enum and the 4000-char limit, so the schema carries the parameter burden. The description adds no additional meaning beyond 'fact,' so the baseline 3 applies.

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

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

The description names a specific action and target: 'persist a fact' into 'the authenticated user's memory.' It is clearly distinguishable from the read-side sibling bee_memory_search, though it never names that sibling explicitly to reinforce the contrast.

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

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

'Use only when the user intends Bee to persist a fact for future conversations' is an explicit gating condition with an intent-based trigger, which is stronger than most. It does not name the alternative tool (bee_memory_search) or state when NOT to add, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered. The description adds genuinely new behavior: results are ranked, memories are not mutated, and retrieval is gated by the user's memory setting and tenant policy — policy/auth context not derivable from 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 tight sentences, front-loaded with the use case followed by behavioral guarantees. Minor redundancy: "without changing them" restates the readOnlyHint annotation, so one clause does not fully earn 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 2-parameter read tool with full schema coverage, no output schema, and complete annotations, the description covers purpose, gating behavior, and mutation safety. It does omit return shape (fields, score/rank format) and pagination or empty-result behavior, which an agent might want.

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 query ("What to recall") and top_k ("How many memories to return") are already documented. The description only implies ranked return ordering and adds no syntax, format, or default guidance beyond the schema; baseline 3 applies.

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

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

States a specific verb (recall) and resource (the authenticated user's Bee memory) and enumerates the content classes it covers: facts, preferences, projects, skills. This clearly separates it from the sibling write path (bee_memory_add) and from document-oriented siblings like bee_documents_search 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?

"Use to recall facts, preferences, projects, or skills from the authenticated user's Bee memory" gives a clear trigger context, but it names no alternatives and states no exclusions (e.g., when to prefer bee_documents_search or bee_chat context). Clear context without routing rules.

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 and destructiveHint=false, so the safety profile is covered structurally. The description still adds value beyond them by enumerating the return payload (status, candidates, scores, result, QPU or fallback evidence, usage, receipt ID) and reaffirming the read-only nature with 'without changing the job' — meaningful given there is no output schema.

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

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

Two tightly written sentences with zero filler; the action and scope come first and the return inventory follows. Every clause earns its place.

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

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

For a single-parameter, non-destructive read with no output schema, the description supplies both the scoping context (tenant-scoped, one job) and the return fields, which is the main gap an agent would otherwise face. It omits any mention of error/not-found behavior or cross-tenant access limits, keeping it short of a 5.

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?

There is a single parameter (job_id) with 100% schema description coverage, so the schema already documents it as a 'Job UUID'. The description adds no format, sourcing, or lookup guidance beyond that, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb (inspect) and resource (one tenant-scoped Lab/quantum reasoning job), plus what it returns. It distinguishes itself implicitly from the plural sibling bee_quantum_reasoning_jobs by emphasizing 'one ... job', but never names a sibling explicitly, 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?

'Use to inspect one tenant-scoped Lab job' implies the retrieval use case but gives no explicit when-to-use vs when-not, no mention of alternatives such as bee_quantum_reasoning_jobs for listing or bee_quantum_reasoning_run for executing. 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 declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds two useful facts the annotations do not: results are tenant-scoped ("authenticated tenant's") and returned as paginated metadata. That is a modest addition on top of an already-complete annotation set.

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 read-only/scoping constraint front-loaded after the purpose statement. No filler, though the "Use to..." opener is mildly formulaic.

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?

It correctly tells the agent this is a paginated read that mutates nothing, which covers the main risk for a list tool with no output schema. However, with four filter parameters at 25% schema coverage, the description leaves an agent unable to tell what limit/model/status actually do.

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 only 25% — only cursor is documented — and the description mentions nothing about limit, model, or status filters beyond the word "paginated." With low coverage the description should compensate for the undocumented filter parameters but does not.

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 (the tenant's retained Quantum Reasoning Lab jobs and capabilities), scoping it to the authenticated tenant. It is clearly distinct from bee_quantum_reasoning_get/run/remove in intent, though it never names those siblings 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?

"Use to list..." plus "without creating or changing jobs" implicitly steers the agent away from run/remove, but no alternative tool is named and no condition (e.g. looking up a single job by id → bee_quantum_reasoning_get) is given. Usage 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 destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety bar is largely met structurally. The description adds real context beyond that: permanence of the erasure, tenant scoping, and the eligibility constraint that the target must be queued or terminal. It does not describe confirmation behavior or what happens when the job is ineligible.

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 precondition front-loaded, so the warning is read before the action. 'Destructive' partially duplicates the destructiveHint annotation, though pairing it with tenant-scoped scope information keeps the sentence largely earned.

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 destructive tool whose annotations already carry the safety profile, the description covers preconditions, scope, and outcome (cancel vs permanent erase) adequately. It omits error behavior for ineligible jobs and any notion of return or confirmation, which there is no output schema to cover.

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% for the single required parameter job_id, so the schema contributes nothing. The description never explains the parameter's format or source, only implying indirectly that the referenced job must be queued or terminal. With low coverage the description should compensate and does not.

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: cancel an eligible queued job or permanently erase content from a terminal job. That is far more specific than the title and tells the agent the two modes of this 'remove' tool. It does not, however, name or distinguish itself from siblings like bee_quantum_reasoning_get or bee_quantum_reasoning_jobs, which an agent would need to choose correctly.

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 an explicit gating condition ('Use only after explicit user intent') and implies when each mode applies (queued = cancel, terminal = delete). It stops short of naming alternatives such as inspecting job state first via bee_quantum_reasoning_get or listing jobs before removing one.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds genuinely new context on top: the job is durable, tenant-encrypted, metered, may incur simulator or QPU cost, and returns a job record. That cost and retention disclosure is the kind of information annotations cannot 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 short sentences, precondition front-loaded, and the follow-up tool named last. Every sentence carries information; sizing is appropriate for a metered, potentially costly operation.

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

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

No output schema exists, and the description usefully says a job record is returned and how to inspect it, which covers the return-value gap. However, for a mutation tool with three required parameters and sparse schema documentation, the parameter meaning and cost/product eligibility rules are left incomplete.

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 only 25% (only 'prompt' is documented). The description does not explain what 'model' (bee-hive/bee-swarm) or 'product' (simulation_cloud/managed_qpu/byopa_managed) mean, nor when provider_connection_id is required versus optional. With three required params and low coverage, the description should compensate and does not.

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 ('Creates') plus resource ('Quantum Reasoning Lab job') with qualifiers (durable, tenant-encrypted, metered). It is clearly distinguishable from the sibling read tool bee_quantum_reasoning_get, which it names as the inspection follow-up.

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?

States an explicit precondition ('Use only after the user chooses an eligible hosted quantum product') and routes the agent to bee_quantum_reasoning_get for inspection. It does not, however, contrast with bee_quantum_reasoning_jobs or say what to do if no eligible product was chosen.

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, openWorldHint and destructiveHint=false, so the safety bar is met. The description adds real value beyond them: the return payload shape ('research text or sample framework code') and an explicit side-effect boundary ('it does not submit QPU work'). It does not cover auth needs, rate limits, or latency, which is why it is 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 dense sentences, front-loaded with the capability, then the return shape, then the alternative. Every clause carries information and there is 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?

With no output schema, the description correctly compensates by stating what is returned. It covers purpose, return type, side-effect boundary, and the sibling alternative, leaving only minor gaps such as supported framework values and what 'NISQ-honest' constrains in the output.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning by mapping natural-language intents to the terse enum values: 'draft a NISQ-honest quantum-circuit design' clarifies quantum_design, and 'critique an ML/CS paper' clarifies paper_critique. It does not clarify the free-form 'framework' or 'focus' inputs, which remain thin 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 states specific verbs and resources: 'draft a NISQ-honest quantum-circuit design' or 'critique an ML/CS paper'. It also differentiates from the sibling bee_quantum_reasoning_run by name, so an agent can route without opening either schema.

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

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

It clearly states the two use contexts (design drafting, paper critique) and names the correct alternative for a different need ('Use bee_quantum_reasoning_run for a durable hosted Lab job'). It lacks guidance against other plausible siblings like bee_chat or bee_code, but the primary routing decision is explicit.

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

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

Annotations already establish the safe-read profile (readOnlyHint=true, destructiveHint=false, idempotent, openWorld). The description goes beyond them by disclosing the output nature ('analysis and remediation guidance only') and an explicit refusal/safety policy around unauthorized weaponization, which an agent cannot infer from annotations. It stops short of describing output shape or latency, but this is meaningful added context.

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

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

Two sentences: the first front-loads what the tool is for, the second front-loads what it will not do. Every clause carries information and there is no filler or repetition.

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

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

With no output schema, the description usefully states that the return is analysis and remediation guidance rather than scan results. Combined with annotations covering the safety profile and a 100%-documented schema, an agent has what it needs to call the tool; only the exact output format/verbosity is unspecified.

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 enum values and the per-field conditions (context for pentest_assist, framework for threat_model, language for code_audit) are fully documented in the schema. The description only restates the task domains in prose and adds no syntax, format, or constraint detail beyond what the schema already provides.

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 four concrete security functions (code audit, threat model, pentest support, smart-contract review) plus the resource type it operates on, so an agent can tell it is an analysis/remediation tool rather than a scanner. It does not explicitly contrast itself with siblings such as bee_code or bee_smith_assurance, 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 opening 'Use for ...' clause gives clear invocation contexts, and the second sentence states hard exclusions (no target scanning, no exploit execution, refuses unauthorized weaponization). It never names an alternative sibling to route to when the exclusion applies, so it stops short of full when/when-not/alternative coverage.

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 and openWorld, so the safety profile is covered. The description adds genuinely useful context beyond that – that authorization is a prerequisite and that the output is internal automated assurance rather than certification – but says nothing about what artifacts the run returns, cost, latency, or what happens to supplied evidence.

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

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

Two sentences, no filler, with the action and target front-loaded and the scope disclaimer trailing where it belongs. The jargon ('Commission Smith for...') costs a little clarity, 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?

With no output schema, 4 required parameters, and 20% schema coverage, the description is not complete enough: it never defines the task modes, the expected evidence format, or what the run produces. For a multi-mode assurance tool this leaves the agent guessing at invocation details.

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 only 20% across 5 parameters, so the description carries most of the burden and does not deliver. It alludes to 'target' and 'authorization_scope' but never explains the five task enum values (engagement_plan, control_assessment, evidence_review, red_team_plan, release_disposition), the profile enum, or what 'evidence' should contain.

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?

It gives a specific verb and resource – commissioning a critical-systems assurance review against a customer-owned or explicitly authorized target – and the second sentence carves out scope ('not government certification or an external-independent audit'). It stops short of naming any sibling tool (bee_security, bee_verify_provenance), and 'Smith EIC' is never defined, so an agent cannot fully distinguish this from related Bee operations.

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 states a precondition (target must be customer-owned or explicitly authorized) and a negative boundary (not a certification or independent audit), which implies when the tool is appropriate. It never names an alternative tool or a competing condition, so the routing decision versus bee_security or bee_verify_provenance is left 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 already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description still adds value by enumerating the returned content (pooled tokens, per-tier allowances, reset times, 24h/7d breakdown) and reaffirming it never mutates billing/credits/entitlements.

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 purpose, then return contents, then the mutation disclaimer. No filler and nothing that could be cut 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?

There is no output schema, so the description carries the burden of describing returns, which it does at a summary level (pooled tokens, allowances, reset times, breakdown). Given a single optional enum param and read-only annotations, this is nearly complete, lacking only detail on result granularity or limits.

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 'window' parameter has a fully documented enum. The description's '24-hour or 7-day breakdown' mirrors the schema's own enum semantics without adding syntax or defaults beyond what's already documented, 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 ('inspect') and exact resource ('the authenticated caller's Bee plan and metered consumption'), which cleanly separates it from every sibling (chat, code, documents, memory, quantum jobs). An agent can route to it without opening the schema.

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

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

The opening 'Use to inspect the authenticated caller's...' gives clear usage context, and 'It never changes billing, credits, or entitlements' implicitly scopes out mutation-oriented intent. However, it never names an alternative tool or states an explicit when-not condition beyond the mutation disclaimer.

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 structurally. The description adds beyond that by stating it "does not alter or replay the session" and by enumerating the returned artifacts (verification status, sealed-turn count, signature details), which tells the agent what verification actually reports.

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 compact sentence pair with the action and key parameter front-loaded, followed by the return payload and the non-mutation guarantee. No filler, no repetition of the title.

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

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

No output schema exists, so the description rightly carries the return-value burden and does so by naming the three returned items. For a single-parameter read tool that is nearly complete; only failure modes (e.g., what happens for an unknown or unsealed session_id) are left unstated.

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

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

There is a single parameter with 100% schema description coverage, so the schema already defines session_id. The description only restates that verification is keyed on session_id and adds no format, source, or lookup guidance beyond the schema, which is the correct baseline of 3.

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 (verify) and resource (a Bee agentic coding session) keyed on session_id, and names what the result contains. It does not differentiate itself from any sibling tool by name, though the sibling set is mostly unrelated, so the gap is minor.

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

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

"Use to verify a Bee agentic coding session by session_id" gives the triggering context, so usage is implied, but there are no explicit when-not conditions and no alternative tool is named for adjacent needs (e.g., inspecting a session vs. verifying it).

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