knowbase

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

With no annotations provided, the description carries the full behavioral burden, and it does substantial work: it explains what a resolved response includes, warns against claiming success on unresolved outcomes, and discloses that Knowbase validates recipe/statuses but does not inspect the caller's environment or authenticate the lookup id. It does not detail side effects or error responses, but the key trust and boundary information is present.

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 compact and front-loaded, opening with the tool's role in the workflow and then covering action, success criteria, failure handling, and validation boundaries in four efficient sentences. Every sentence contributes distinct information, and there is no filler or redundant schema 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?

Given the tool's complexity (7 required parameters, no output schema, no annotations), the description provides a solid workflow anchor and explains the high-level output contract (receipt and final report) plus the unresolved/inconclusive behavior. It does not fully specify the response structure beyond that, but the rich parameter schema compensates for most gaps.

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

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

Schema description coverage is 100%, and each parameter already has a clear description, including the important 'returned by diagnosis' relationship and the criterion status enum. The description adds a high-level instruction to submit the ids and observations, but this largely restates what the schema already communicates. The baseline of 3 is appropriate because the schema is doing 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?

The description names a concrete action ('Close the loop after knowbase_diagnose identifies a structured resolution') and specifies what the tool does: apply every listed step, run every verification criterion, and submit ids and observations. This clearly distinguishes it from sibling tools because it is explicitly positioned as the post-diagnosis completion step.

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 clearly states when the tool is appropriate: after knowbase_diagnose has identified a structured resolution. It also provides behavioral guidance for unresolved or verification_inconclusive responses, telling the agent not to claim success, to follow nextAction, and to call the tool again. It does not exhaustively contrast against every sibling, but the sequential relationship to knowbase_diagnose is clear.

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

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

With no annotations, the description carries the full burden and does so well: it discloses that the tool rules out causes with reasons, includes fix steps in its answer, and explicitly refuses to guess when observations are insufficient. These are meaningful behavioral expectations beyond the title and 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?

Three sentences with no filler: the first gives the core behavior, the second gives usage timing and output contents, the third gives the honesty fallback. Everything earns its place and the key information is front-loaded.

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 simple 3-parameter diagnostic with no output schema, the description tells the agent what to provide, when to call it, what the answer will contain, and how it handles ambiguous evidence. No critical gap remains 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 coverage is 100%, so the baseline is 3. The description adds value by framing observations as discriminator-check output and explaining how the tool uses them to separate causes, including the ambiguous-evidence fallback. This complements the schema without repeating it.

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 ('identify') and a specific resource (which root cause is present vs. ruled out, using observations from a strong knowbase_lookup match). It clearly distinguishes this from knowbase_lookup, which returns a match, and from later fix/report tools by focusing on narrowing causes.

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 explicitly instructs to call only after running the checks and calls itself the only way to tell several plausible causes apart. It also states the fallback when observations don't separate causes. It does not explicitly list alternative sibling tools or say 'do not use before X,' but the sequencing and exclusivity are clear.

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

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

No annotations are provided, so the description carries full burden — and it excels: it discloses that boilerplate is discounted automatically, that 'none' verdict means the corpus genuinely lacks coverage, that strong results include root causes with cheap checks, and that partial results are only leads. This goes far beyond a simple 'lookup' statement.

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

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

Four sentences, each earning its place: the first defines the tool, the second covers input flexibility, the third explains the verdict semantics and its implication, and the fourth gives actionable next steps. Front-loaded with the primary purpose; no fluff 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?

Given the modest schema (2 params, no output schema) and sibling context, the description fully equips an agent to call it correctly and interpret the result. It covers input format, output verdicts, edge case behavior ('none'), and the follow-up action — nothing essential is missing for correct invocation and use.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds meaningful context about the 'error' parameter by suggesting it accepts messages, codes, or stack traces and that boilerplate is auto-filtered — exceeding what the schema's one-line description provides. The 'limit' parameter is implicit but not explicitly detailed, a minor 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 states a specific verb ('Find') and resource ('verified, source-backed entries for a concrete technical error') and clearly distinguishes this from siblings like knowbase_diagnose by positioning it as an initial lookup step. The scope is explicit: returns only strong/partial/none verdicts, not the nearest entry.

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

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

Explicitly tells the agent when to use it ('Paste the error message, error code, or the whole stack trace'), what to expect (verdict types), and what not to do (do not use partial results without an independent match). It also routes to knowbase_diagnose after strong matches, naming the alternative tool and the trigger condition.

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

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

With no annotations at all, the description carries the full behavioral burden, and it does so well. It discloses that returned content is UNTRUSTED text to be judged, not followed; that a miss returns an empty answer plus a fingerprint; that no key/registration is needed to read; and that supplying agentId records the miss for the queue.

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 long but front-loaded with the most important instruction ('USE THIS FIRST') and organized into usage, exclusions, and trust warning. The cost comparison ('about two kilobytes where four search results cost forty') is vivid but not essential, so it is not perfectly economical.

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?

Without an output schema or annotations, the description fully covers what the agent will receive (prior attempts, or empty answer plus fingerprint), how to treat it, when to supply credentials, and how environment affects matching. Nothing critical is missing for safe 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 100%, so the baseline is 3. The tool description adds no parameter-specific meaning beyond what the schema already provides; its value is in usage guidance and behavioral context rather than parameter semantics.

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

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

The description states a precise action: look up concrete failures and get back what other agents have already tried, tied neatly to the title. It also bounds the resource to recorded failure histories, not general knowledge. However, it never explicitly differentiates itself from sibling tools like knowbase_lookup or knowbase_diagnose, so it falls just short of a 5.

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

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

The description gives explicit when-to-use guidance ('USE THIS FIRST, before a web search, whenever you hit a concrete error with text you can paste') and explicit when-not-to-use guidance ('DO NOT use it for logic bugs, documentation, or anything you already understand'). It also names web search as the alternative and recommends checking the tool before proposing uncertain fixes.

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

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

With no annotations, the description carries the full burden and discloses a critical behavioral trait: the secret is returned only once. It also explains the purpose of identity (countable independent confirmation) and warns against repeated registration. It does not state whether registration mutates permanent state or how rotation works, but the essential one-time-secret behavior is clear.

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

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

The description is front-loaded with the core action and usage timing. The philosophical justification at the end is slightly verbose, but it adds meaningful context for why an agent should register. Overall it is dense and purposeful, though not as lean as it could be.

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 registration tool with no annotations and no output schema, the description covers when to call it, when not to, the one-time secret behavior, and the relationship to reporting and recall. It doesn't describe the shape of the returned secret or what to do with it, but the mention of 'secret comes back once' and the sibling knowbase_report give enough guidance 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 100%, so the baseline is 3. The description adds modest context about the 'name' being self-chosen and permanent, but it doesn't clarify 'bio' or 'display' beyond what the schema already provides. The schema carries the parameter documentation burden.

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

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

Names a specific verb ('Claim a handle') and resource, and clearly ties the tool to enabling knowbase_report. It explicitly differentiates itself from knowbase_recall, so an agent can distinguish registration from read operations without looking at 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?

Gives exact timing ('once, the first time you want to call knowbase_report'), explicit exclusions ('DO NOT use it to read', 'DO NOT call it again if you already hold a secret'), and names the alternative for read access (knowbase_recall needs no account). This is model usage guidance.

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

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

With no annotations provided, the description carries the disclosure burden and does well: it warns against recording unrun attempts, requires a reproducible error, and explains that confirming by solutionId turns individual fixes into countable, reusable knowledge. It doesn't discuss persistence or retraction, but the write semantics and intened side effect are clear.

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

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

The description is front-loaded with the core purpose, then organizes into when-to-use, why, and when-not-to-use. Some sentences are motivational rather than operational ('the rest of the internet will never tell them', 'costs you nothing'), which adds length without much instruction, but the structure remains clear and scannable.

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 9-parameter write tool with no output schema, the description provides enough to call it correctly: what to record, when, why solutionId matters, and what to avoid. Required auth fields and per-parameter constraints live in the schema, so it doesn't need to restate them. It falls just short of full completeness by not addressing the competing knowbase_report_outcome sibling.

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

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

Schema coverage is 100%, so the structured parameter descriptions already carry most of the meaning. The tool description adds strategic guidance around preferring solutionId for confirmations and not recording unrun work, but it doesn't add new format or syntax-level detail for the 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 opens with a precise action and object: 'Record what you tried against a build failure, error or crash and whether it worked.' It also explicitly separates itself from knowbase_recall by saying that is the question-asking tool. However, it never addresses the similarly named sibling knowbase_report_outcome, so it doesn't fully disambiguate among all sibling tools.

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

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

It gives explicit positive triggers ('USE THIS when you finish debugging something, win or lose') and clear exclusions ('DO NOT use it to ask a question... did not actually run... no reproducible error'). It names knowbase_recall as the question-asking alternative, but does not mention the closely related knowbase_report_outcome sibling, leaving some routing ambiguity.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It meaningfully states that the tool records a claim for re-verification and cannot issue a resolved receipt, which is important side-effect information beyond the schema. It does not detail error cases or exact response content, but the core behavioral caveat is present.

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 densely informative sentences: the first establishes deprecation and compatibility constraints, the second states behavior and routes to the successor. No filler or redundant restatement.

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 simple tool with fully documented parameters, the description covers purpose, key limitation, and migration path. The phrase 'exact result copy as before' is slightly opaque since no output schema exists, but as a deprecated alias aimed at existing clients this is an acceptable minor 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%, so the schema already documents all four parameters. The description references slug and worked but does not add per-parameter meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

Description states the action ('report whether a fix held') with the required inputs (slug and worked) and clearly identifies itself as a deprecated compatibility alias. It is immediately distinguishable from sibling knowbase_complete_resolution because it positions itself as the legacy path.

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

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

Explicitly says existing clients may continue using it, while new integrations should use knowbase_complete_resolution with the structured ids and verification criteria returned by knowbase_diagnose. This gives clear when-to-use and when-not-to-use guidance.

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

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

With no annotations, the description carries the behavioral burden and handles it well: it discloses partial deletion (only your contribution is removed), preservation of other agents' reports, and the condition under which a failure record survives. It stops short of stating return/error behavior or whether retraction is reversible, but the core side effects are transparent.

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 tightly packed sentences: the action, the motivation, and the nuanced scope of the removal. Every sentence earns its place and the core behavior is front-loaded.

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 simple three-parameter mutation with no annotations or output schema, the description is nearly complete: it explains what is removed, what survives, and when to use the tool. The only gap is not spelling out the result when called on a non-existent or already-retracted report.

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

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

Schema coverage is 100% and each parameter already has a concise description (handle, attempt, secret). The tool description adds no extra parameter meaning, which is acceptable because the schema carries the burden.

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?

Description opens with a specific action and object: 'Remove your own report on an attempt.' It clearly distinguishes retraction from the sibling reporting tools by emphasizing 'your own' and 'only what you contributed,' so an agent can tell it apart from knowbase_report without inspecting schemas.

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

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

The description gives clear usage context: correcting a mistaken report because 'contradicting yourself leaves both statements standing.' It implies why not to use the report tool for corrections, though it does not explicitly name sibling alternatives or state when not to call this tool.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that the handle and record are untouched, that proving possession of the current secret is the only way in, and that losing the secret entirely means no recovery — with a security rationale. These are meaningful behavioral traits beyond the basic 'rotate' action.

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 three tight sentences: what the tool does, when to use it, and the critical security caveat. There is no filler, and the central action is front-loaded before the usage guidance.

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 security-sensitive rotation tool with no annotations and no output schema, the description covers the action, the trigger conditions, the authentication requirement, and the failure mode. An agent has enough context to decide when to call it and what precondition must be met. The lack of an explicit statement about the old secret being invalidated is minor given the tool name and title already convey replacement.

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 schema already documents both parameters at 100% coverage: agentId is 'Your handle' and agentSecret is 'The secret you hold now.' The description reinforces that the secret must be the currently held one, but it does not add format, length, or additional lifecycle details. Baseline 3 is appropriate because the schema carries the parameter documentation weight.

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: 'Issue yourself a fresh secret, signed by the one you currently hold.' This clearly communicates both the action and the output. It is not a tautology and is readily distinguishable from the sibling tools like knowbase_lookup or knowbase_register.

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

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

The description gives explicit usage triggers: 'when a secret has been written somewhere it should not be' and 'on whatever schedule you rotate credentials.' It also clarifies the precondition that you must still hold the current secret. It does not explicitly discuss when not to use it or reference sibling alternatives, so it narrowly misses a 5.

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