ColossalCapital — Akashic Corpus & Agentic Platform

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

The annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior: the call is asynchronous, returning a run ID and status rather than completed results. It omits re-run semantics, cost/duration, and any state changes triggered, which matters for a non-idempotent trigger.

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

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

Two short sentences, action first, return value second, with no filler. It is efficient, though the brevity reflects under-specification rather than tight editing.

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 restated, but with 0% schema coverage on three params and no usage guidance for a non-idempotent trigger, the definition leaves too much for an agent to guess before a correct call.

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

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

Schema description coverage is 0% across three parameters, so the description must compensate and does not. repo_path is required but its expected form (absolute path, URL, corpus identifier) is unstated, and entity_id/interaction_id defaults are never explained.

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: 'Trigger analysis on a repository,' which is recognizable as an async kickoff action. No sibling tool performs analysis, so it is distinguishable in practice, but the description makes no explicit contrast with alternatives.

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 call this versus other tools, what preconditions must hold (account/agent registration, corpus state), or whether it should be re-run. The agent must infer usage entirely 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 (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false) already declare this can mutate external state without being safe to retry. The description surfaces the two execution modes, which is genuinely beyond the annotations, but says nothing about what a trigger actually does (open PRs? post comments? notify agents?) or that it is non-idempotent, which matters 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 front-loaded sentences: capability first, then the monitor inventory. The eight-item list is long but earns its place by telling the agent what the tool covers; 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?

An output schema exists, so return values needn't be explained. However, with a mutating trigger path and an undocumented entity_id, the definition leaves out information the agent needs before invoking it on a live system.

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 both parameters depend on the description. 'trigger_check' is only obliquely implied by 'trigger a manual heartbeat check cycle', and 'entity_id' is never mentioned at all — the agent cannot tell whether it takes a repo, org, agent, or monitor ID.

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

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

States a specific verb+resource ('List heartbeat monitor status') plus a second mode ('trigger a manual heartbeat check cycle'), and enumerates the eight monitors so the agent knows the domain covered. No sibling overlap exists among the listed tools, so differentiation is a non-issue rather than a gap.

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 two modes are named but not disambiguated: nothing says when an agent should just read status versus when it should trigger a check cycle, nor what entity_id scopes. Usage is implied by the mode names only, with no exclusions or preconditions.

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 non-read-only, open-world, non-idempotent, non-destructive behavior, so the bar is lower. The description adds genuinely new context: a cryptographic signature over 'claim:{agent_id}:{entity_id}' is required and both parties must consent, plus the important side-effect detail that the agent retains its own identity.

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 what the tool does, followed by the hard prerequisite (signature) and the identity caveat. No filler; every clause adds information an agent needs.

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

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

Output schema exists, so return values need not be explained, and the signature/consent model is well covered. But for a 5-parameter mutation tool with zero schema coverage, the silence on scopes and workspace_scope leaves an agent unable to fill the optional arguments correctly.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It clarifies the signature payload format and implicitly ties agent_id and claimant_entity_id to that payload, but 'scopes' and 'workspace_scope' are never mentioned anywhere, leaving two of five parameters completely 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?

Uses a specific verb ('Bind') and resource (registered agent → user/org account) and names the mechanism ('acted_for grant'). It is reasonably distinct from register_agent, though it does not explicitly contrast itself with that sibling, leaving the register-vs-claim boundary 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?

The consent framing ('the agent consents, and the account consents') implies this is a post-registration linking step requiring a signature, which hints at prerequisites. However, it never states when to use this instead of register_agent, nor any exclusions or failure conditions.

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 that results include item counts per domain, which is content-level context rather than behavior. It says nothing about ordering, whether the list is exhaustive or filtered, or how the optional product scope affects results.

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, front-loaded with the action and resource, with the numeric scope and downstream consumers packed in without filler. Every clause adds information.

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 structure needn't be described, and annotations cover the safety profile. The remaining gap is the entirely undocumented "product" parameter and no indication of whether the 261-domain listing is complete or scoped when that parameter is supplied.

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 "product" parameter, so the description carries the full burden — yet it never mentions the parameter at all. An agent cannot tell whether "product" narrows the 261 domains, filters counts, or is a display toggle.

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 and resource ("List the corpus domain lanes") and quantifies scope (261 domains of repos, docs, code examples, issues) with item counts. It also positions itself relative to siblings by calling itself "the discovery index for corpus_route and corpus_item," though it doesn't distinguish itself from the more similarly named search_corpus.

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?

Naming itself the discovery index for corpus_route and corpus_item implies a browse-then-route workflow, which is useful context. However, there is no explicit "use this first when you don't know the domain" instruction, no when-not guidance, and no mention of search_corpus as an alternative entry point.

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

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

Annotations already cover readOnly/idempotent/non-destructive, so the bar is lower. The description still adds meaningful behavior the annotations cannot express: access is filtered by the caller's visibility class, and gated items return an account_required pointer instead of an error or empty result — a trait an agent must know to interpret the response correctly. It omits what happens for a nonexistent item_id, which keeps it below 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?

Two short sentences, zero filler, with the core operation stated first and the access-control caveat second. Every clause carries information.

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 and annotations carry the safety profile, so the description needn't explain return shape. Still missing for a simple single-parameter tool: the format of item_id and any hint about how this differs from the near-identically named sibling read_corpus_item.

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 sole parameter item_id has no documentation in the schema. The description never mentions item_id, its expected format (ID, slug, prefix), or whether it is required, 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 specific verb and resource ('Read one corpus item's full record') and enumerates what the record contains (evidence, license, quality, tags). However, it never distinguishes itself from the sibling tool 'read_corpus_item', which appears to promise the same operation, leaving the agent to guess which one to call.

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 visibility-class sentence implies usage context (some items are gated and return a pointer rather than data), which is useful. But there is no explicit guidance on when to prefer this over search_corpus or read_corpus_item, and no stated prerequisites for calling it.

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

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

Annotations already declare the safety profile (not read-only, not destructive, open-world, non-idempotent). The description adds genuinely useful context that anonymous reports are weighted down, but it never states what the report actually changes on the corpus side or whether repeat reports accumulate, which matters for a non-idempotent write.

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 compact sentences with the core action front-loaded and no filler. Minor jargon ('routing flywheel') costs a little clarity but the sentence still earns its place by explaining the payoff of reporting.

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 cover safety. However, for a four-parameter write tool with 0% schema coverage, leaving 'domain' and 'note' undefined and the effect of the report unstated leaves an agent guessing at 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, so the description must carry the load. 'Cited corpus item' loosely maps to item_id and 'helped' to success, but domain and note are entirely unexplained, and no allowed values or formats are given.

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: reporting whether a cited corpus item helped, with the downstream effect (improving the corpus/routing). It is clearly distinct from read_corpus_item or search_corpus, though it never names a sibling to contrast against, which keeps it at 4 rather than 5.

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

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

Usage is implied by 'cited corpus item' — report after a corpus item was used — but there is no explicit when/when-not guidance and no mention of alternatives such as corpus_route or corpus_item. An agent can infer the context but not the boundaries.

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 safety (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description still adds real behavior: it discloses the response components and the important edge case that items above your visibility class return an account_required pointer rather than content. It does not cover cost, latency, or whether routing has side effects on the corpus.

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 core action and the return shape front-loaded before the visibility-class caveat. Every clause carries information.

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

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

With an output schema present, the description needn't enumerate return fields, and annotations carry the safety profile; what remains is a clear statement of what routing does and the account_required fallback. The only substantive gap is the undocumented domain parameter.

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 both parameters (task, domain with default 'general') are undocumented structured fields and the description must compensate. It says nothing about what form the task should take or what values domain accepts and how 'general' behaves, leaving the second parameter entirely 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 (route) and resource (a task to the best corpus item), plus what comes back (decision kind, picked item, score, citations). It is distinguishable from read-only siblings like corpus_item or read_corpus_item, though it never names search_corpus, the closest alternative, and 'Laya' is unexplained.

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 rather than stated: the mention of 'decision kind' and 'score' suggests this is for choosing among candidates rather than fetching a known item, which points away from read_corpus_item. But there is no explicit when-to-use, when-not, or named alternative versus search_corpus.

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

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

The annotations already disclose that this is not read-only, is open-world, is not idempotent, and is not destructive. The description adds only that the result is a drafted plan with stages, but it does not explain side effects, persistence, permissions, or what 'drafting' changes in the workspace.

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 short and front-loaded, with the core operation stated first and the return shape second. The second sentence is somewhat redundant because an output schema exists, but the overall structure has little waste.

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

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

For a five-parameter, open-world, non-idempotent drafting tool with no parameter documentation in the schema, the description is too thin. The output schema covers return values and annotations cover safety flags, but the description still omits prerequisites, effects, and parameter meanings.

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 needs to compensate for five undocumented parameters. It only loosely maps 'ticket or repository' to `derived_from_ticket` and `source_repo`, leaving `workspace_id`, `environment`, and `cicd_provider` unexplained.

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 states a specific verb and resource: 'Draft a deployment plan,' and identifies the source as 'a ticket or repository.' That is clear enough to understand the basic operation, but it does not distinguish this from the related sibling `generate_cicd_workflow`.

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 no explicit when-to-use guidance, prerequisites, or alternatives. Mentioning that the plan is drafted from a ticket or repository only hints at the input context and does not tell an agent when to choose this tool over its 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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is fully covered. The description adds that results carry RBAC context (identity, role, required permission, eligibility), but this is largely restating what the output schema already conveys and says nothing about ordering, volume, or staleness of pending items.

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: the capability and its returned context first, the use case second. No filler, everything 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?

An output schema and rich annotations carry most of the load, so the description needn't explain returns. However, with both parameters undocumented in the schema, the description should have clarified valid status values and category semantics; it does not.

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%: 'status' and 'category' have only titles and defaults. The description mentions 'pending' items, hinting at the status default, but never explains what other status values exist or what categories mean/filter, leaving the agent to guess at the one meaningful filter parameter.

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

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

States a specific verb and resource (fetch pending HITL approval items) plus the RBAC payload it returns, so the agent knows exactly what this tool provides. No sibling tool covers HITL approvals, so explicit differentiation isn't needed, but the description doesn't say so.

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 this to check what needs human approval before proceeding" gives a clear triggering context and even implies workflow placement. It stops short of naming when not to use it or pointing to any alternative path for already-approved/denied items.

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 the operation is non-read-only, non-destructive, non-idempotent and open-world; the description adds value by disclosing the return payload (YAML, filename, stages, research basis). However, it never resolves the critical ambiguity of whether the workflow file is written into repo_path or merely returned — a material distinction for a non-idempotent, open-world mutation.

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 action and resource, then the return shape. No filler; the only minor inefficiency is that the return-value sentence duplicates what the output schema already provides.

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 documentation is not required, yet even with that credit the definition leaves an agent under-informed for a 7-parameter, non-idempotent generator: the fate of repo_path (read vs write), what tier changes, and how deploy_* interact with the deploy stage are all unaddressed.

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, so the description must compensate and largely doesn't. It usefully implies the provider enum values (GitHub Actions, Bitbucket Pipelines, GitLab CI, Tekton) and hints at test/build/deploy parameters via the stage list, but repo_path, tier, deploy_enabled, and deploy_environment get no semantic treatment at all.

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 (generate) and a concrete resource (CI/CD workflow), and enumerates the four supported providers plus the stage composition, which is far more than a restated title. It stops short of distinguishing itself from the sibling draft_deployment_plan, which is the closest adjacent artifact-producing tool.

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

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

Usage is only implied: the provider list tells an agent this is the tool for scaffolded CI config, but there is no explicit when-to-use/when-not statement and no pointer to draft_deployment_plan as the alternative for planning rather than generating files. An agent must infer the boundary from the name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that the guide is canonical and covers every caller class, which helps set expectations, though it does not discuss output format or 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 short sentences with the core resource and caller classes front-loaded. The usage instruction follows naturally and 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 an output schema present, the description need not explain return values. Annotations cover safety, there are no parameters, and the description identifies the tool's scope and when to call it, so nothing material is missing.

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

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

The tool has zero parameters, so there are no parameter semantics to explain. The baseline for a parameterless tool is 4, and the description correctly does not invent parameter 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?

States a specific verb ("Returns") and resource ("canonical onboarding flow"), and enumerates the caller classes it covers. An agent can distinguish this from sibling registration tools because it describes a guide, not an action like register_agent.

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 "Call this first if you're unsure how to proceed," giving a clear condition for use. It does not name when not to use it or point to specific alternatives, but the guidance is sufficient for a zero-parameter guide 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds a meaningful behavioral fact beyond that — no authentication is needed — which an agent cannot infer from the annotations. It stops short of noting caching or response freshness, a minor 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?

Three short clauses, front-loaded with the resource and the 'use first' guidance. Every sentence carries distinct information: what it fetches, the auth characteristic, and when to call it.

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

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

With an output schema present, the description need not explain return values, and it still summarizes the payload's purpose ('learn what tools and APIs are available'). No parameters plus full annotation coverage means nothing an agent needs to call this correctly is missing.

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

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

The input schema has zero parameters, so there is nothing the description needs to disambiguate; per the baseline this lands at 4. The description correctly implies a parameterless call.

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 and resource — 'fetches llms.txt' and 'discover the platform's public capabilities' — and scopes it as public/no-account, which distinguishes it from account-gated siblings like register_account or list_llm_keys. An agent can tell what this returns without opening the schema.

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

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

'No account required. Use this first to learn what tools and APIs are available' gives clear timing and a prerequisite-free context for invocation. It does not explicitly contrast with the closest alternative, get_onboarding_guide, leaving the agent to infer which discovery/onboarding entry point to pick.

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, so the safety profile is covered. The description adds the non-obvious dual behavior (detail mode vs. ID-listing mode) and the scope of the returned chain, which an agent cannot infer from the schema since the parameter has a default of empty string.

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 preamble, with the primary behavior front-loaded and the fallback mode second. Every clause carries information.

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

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

With one optional parameter and an output schema present, the description need not explain return values, and it already covers the dual calling modes. What remains missing is any notion of what an 'interaction' represents or where IDs come from, which matters for an agent unfamiliar with the domain.

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 parameter's meaning; it does explain the consequence of omitting interaction_id (falls back to listing all IDs). That is useful, but it never states the expected format or source of a valid interaction ID, so it only partially compensates 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?

Specific verb ('Fetch') and resource ('interaction chain' for an interaction ID), plus an enumeration of the artifacts returned (heartbeat, analysis, ticket, agent, PR, deployment). That is far more concrete than a tautology, though it does not explicitly contrast itself with any sibling tool.

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

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

It states the mode switch — 'If no interaction_id is provided, lists all known interaction IDs' — which is genuine usage guidance for the only parameter. However, there is no guidance on when to use this versus related lookup paths (corpus_item, fetch_hitl_items) or any prerequisite/context for what an interaction is.

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 and non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond that: the response reports presence of keys and never the secrets, which matters for a BYOK audit call. Return shape details are left to the output schema, which exists.

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

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

Two short sentences, front-loaded with the action and scope, followed by the use case. No filler or redundancy.

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

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

With full annotations, an output schema and no parameters, the description is nearly complete. The one omission is explicit positioning relative to the key-management siblings (set_llm_key, remove_llm_key, list_llm_providers), which an agent must work out itself.

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 and the description correctly describes a parameterless call, so there is nothing to under-specify. Baseline 4 applies.

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

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

States a specific verb (List) and resource (LLM providers with stored keys), and adds the crucial detail that key material itself is never returned. It implies a distinction from list_llm_providers but never names that sibling, so the agent must infer the difference between listing providers and listing stored-key status.

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 check BYOK configuration status' gives a clear triggering scenario for the tool. It stops short of naming alternatives (list_llm_providers, test_llm_key) or when-not-to-use conditions.

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, so safety is covered. The description's added value is the BYOK cost model (inference billed to the user, routing handled by the platform) rather than behavioral detail such as what the listed entries contain or whether the set is static.

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

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

Two short sentences with the core purpose front-loaded. The second sentence is partly promotional but does convey the cost/billing model, which is decision-relevant for a BYOK tool.

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 zero parameters, rich annotations and an output schema, the description needs only to establish scope, which it does. It could be slightly stronger by stating that the results are the provider identifiers expected by set_llm_key, but nothing essential is missing.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The mention of "keys" correctly signals this is the provider catalog rather than a keyed operation.

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?

Clear verb+resource ("List LLM providers") with the added qualifier that these are BYOK-eligible providers. It implicitly separates itself from list_llm_keys (configured keys) and set_llm_key (writing a key), but never names those siblings, so differentiation requires inference.

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 "providers you can bring keys for" implies the use case (discover options before calling set_llm_key), but there is no explicit when-to-use statement, no exclusion, and no named alternative for the adjacent case of inspecting already-stored keys.

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 genuinely new context by disclosing that items above the public class return an account_required pointer instead of content — a non-obvious outcome an agent would otherwise miscount as success.

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, the primary action front-loaded and the edge-case caveat second. Nothing repeats the title or annotations, and every clause carries information.

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 needed, and the access-tier caveat is a useful addition. However, for a single-parameter tool with zero schema coverage, the missing entry_id semantics and absent sibling routing leave real 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 0% and the schema exposes only a bare 'entry_id' string with no format or origin. The description does not describe how to obtain or format an entry_id, so it fails to compensate for the coverage gap on the tool's sole required parameter.

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

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

States a specific verb (read) and resource (public Akashic corpus item) with the scope qualifier 'in full,' which implies retrieving complete content rather than a summary. It does not explicitly distinguish itself from siblings like corpus_item or search_corpus, so the boundary is inferable but not stated.

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: 'in full' suggests use after a search when the complete item is needed. The description never says when to prefer this over corpus_item or search_corpus, despite both being close siblings in the list.

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 the write/open-world/non-idempotent profile, so the description's real contribution is context beyond them: the account is free tier with no billing, creation is immediate, and a link_token is returned to claim the Idio login later. It omits failure modes such as captcha rejection or duplicate-email behavior, 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 tight sentences, front-loaded with the action and its side effects, then the invocation trigger. No redundant restatement of the title 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?

An output schema exists, so return values need not be explained, and the description usefully flags link_token anyway. However, for a five-parameter, non-idempotent registration tool with zero schema documentation, the missing parameter guidance and duplicate/failure semantics leave meaningful 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 0% and the description names none of the five parameters. While name and email are self-evident, captcha_token, use_case, and intended_tier carry real ambiguity (required format, when the token is mandatory, whether tier selection has consequences) that neither schema nor description resolves.

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 ("Register a free ColossalCapital account") and narrows scope to "a human user," which implicitly separates it from register_agent and register_org. An agent can identify the operation and target without opening the schema.

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

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

Gives explicit triggers: call it when a tool returns account_required, or when a user asks to sign up. It does not explicitly say when to prefer register_agent or register_org instead, but the "human user" framing makes the split mostly 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 cover safety (readOnly=false, destructive=false, openWorld=true, idempotent=false), and the description adds real context beyond them: key-only auth with no password, a prepaid wallet created for metered tools, and future rebinding via claim_agent. It does not disclose error behavior (e.g. duplicate name) or whether registration is gated, so it is helpful but not complete.

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

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

Four short sentences, each carrying a distinct fact: what is created, the auth model, the side effect (wallet), and the lifecycle note. The identifying detail is front-loaded and nothing is repeated from 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?

An output schema exists so return values need not be described, and annotations cover the safety profile; the description supplies the auth model and a notable side effect. The remaining gap is failure/duplicate-name behavior and the meaning of the optional identity fields, which for a creation tool matters somewhat.

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 full burden, and it only illuminates ed25519_pubkey as the sole credential. The other three parameters — name, intended_use, and operator_contact — get no explanation of format or role anywhere, leaving the operator_contact vs. wallet relationship ambiguous.

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 and pins the distinction down with '(entity_type=agent)', which separates it from register_account and register_org in the sibling list. An agent can tell what this creates 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?

Explains the credential model ('the Ed25519 public key is the only credential — no password') and points to the follow-up path via claim_agent, which is an explicit alternative/reference. It does not explicitly say when to pick this over register_account or register_org, 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 already cover the safety profile (not read-only, open-world, non-idempotent, non-destructive), and the description adds genuinely non-obvious behavior: existing individual accounts are absorbed rather than recreated. It still omits side effects an agent would want, such as whether invitations are emailed or whether the returned API key is shown only once.

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

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

Three short sentences, front-loaded with the action, then the key behavioral caveat, then the return value. No filler and nothing buried.

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

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

With an output schema present, the description need not explain return shape, yet it still flags the API key. Combined with annotations covering the mutation profile, the remaining gap is only field-level parameter meaning, which is minor at 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% — all four parameters carry only titles and defaults. The description does not explain what name or contact_email are used for (billing contact? admin identity? invitation target?) or what industry affects, so it fails to compensate for the schema 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: 'Register an organization account.' The clause about employees keeping individually-created accounts scopes it to org-level registration, but it never names the sibling register_account as the individual path, so sibling differentiation is only implied.

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 account-preservation sentence hints that this is the org-tier path rather than individual signup, but there is no explicit 'use this when / use register_account instead when' routing, and no prerequisites such as admin authority or email-domain requirements.

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 and idempotentHint=true, so the safety profile is covered. The description adds only that the key lives 'in the vault', but says nothing about irreversibility, permission requirements, or whether the key must exist beforehand — modest added value 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?

A single tight sentence with the resource and target front-loaded. It earns its place but is so brief that economy shades into under-specification.

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. However, for a destructive mutation with two undocumented parameters and zero schema coverage, the description should say more about the scope parameter and the consequences of deletion.

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 both parameters. The description explains neither the required 'provider' parameter's accepted values nor the 'scope' parameter, which defaults to 'entity' and is entirely unexplained anywhere — a meaningful gap the description fails to compensate for.

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

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

States a specific verb+resource: 'Remove a stored BYOK provider key from the vault.' This clearly distinguishes it from the sibling read/set operations (list_llm_keys, set_llm_key, test_llm_key), though the description never names those alternatives 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?

No indication of when to use this versus set_llm_key or test_llm_key, no prerequisites, and no warning that removal is irreversible. The reader must infer usage entirely from the tool name and the word 'Remove'.

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, so the safety profile is covered. The description adds real behavioral context on top: results are restricted to public entries and authentication is not required, which is the key thing an agent must know about what comes back. It stops short of saying anything about pagination or result ordering.

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

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

Three short sentences, front-loaded with the resource definition followed by the access constraint and the upgrade path. Every sentence earns its place and nothing is padded.

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 the public/private scope plus the no-auth constraint are well covered. However, with four completely undescribed filter parameters, an agent cannot confidently construct a query or use technology/stack_layer without experimenting.

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 all four parameters (limit, query, technology, stack_layer) are undocumented beyond bare titles and defaults. The description only faintly gestures at 'stack layers' as a corpus dimension, without explaining how query matching works, what format technology expects, or what limit bounds. It 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 specific verb (search) and a clearly scoped resource (the Akashic corpus), and enumerates its contents — tools, stack layers, design patterns, exemplars. It distinguishes itself implicitly from read_corpus_item/corpus_item by being a search rather than a fetch, but never names those close siblings, so an agent still has to infer the boundary.

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 usage context: public entries only, no account required, and explicitly points to register_account/register_agent when the full corpus is needed. That is a genuine when-to-use routing statement, though it offers no exclusions or guidance versus the similarly-named search_skillfiles or corpus_item.

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 non-destructive behavior, so the safety profile is covered. The description usefully adds what skillfiles represent (behavioral guidance for tests, PRs, linting, review, CI/CD), but discloses nothing about search behavior such as ranking, result limits, or whether empty query returns everything.

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 a compact definition of the resource. No filler; the em-dash clause is dense but earns its place by explaining the domain.

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 and annotations cover safety, so the description only needs to cover usage and search semantics — yet it omits when to pick this over search_corpus and how the two optional filters interact. Adequate but with a real informational gap for an agent choosing among many search tools.

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; 'by query or persona' at least maps the two params to their roles and implies they are alternative retrieval keys. It does not say whether they can be combined, what persona values look like, or what an empty string does, so it only partially compensates 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+resource ('Search for relevant skillfiles') and adds a definition of what skillfiles are, which distinguishes the resource from the sibling corpus tools. It stops short of explicitly contrasting with search_corpus, so the differentiation is implied rather than stated.

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 'by query or persona' hints at two retrieval modes, but there is no guidance on when to use this versus search_corpus or corpus_item, no prerequisites, and no statement about what happens when both parameters are empty (both default to ''). The agent is left to infer selection criteria.

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

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

Adds meaningful behavioral context beyond the annotations: encrypted vault storage, provider-side validation, and the admin-only org scope. However, 'Validated against the provider before storing' is stated unconditionally while the schema exposes a validate boolean defaulting to true, which makes the description slightly misleading if the caller passes validate=false.

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

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

Three short sentences, front-loaded with the core action, followed by behavior and then the prerequisite. Every sentence adds value 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?

Given an output schema exists, the description need not explain returns. It covers storage location, validation, admin restriction, and auth prerequisites, but the provider field's expected values remain unclear for a tool whose primary argument is 'provider'.

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 parameter burden. It explains scope='org' and implies validation behavior, but leaves provider values, api_key format, and the default 'entity' scope unexplained.

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 object: 'Store a BYOK LLM provider key in the encrypted vault.' It is clearly distinguishable from sibling tools like list_llm_keys, remove_llm_key, and test_llm_key, which all operate on the same resource with different verbs.

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 states the prerequisite (call register_account or authenticate first) and the admin-only condition for scope='org'. It does not explicitly say when to use this versus test_llm_key, but the prerequisite routing is strong.

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

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

Annotations already cover readOnly, idempotent, non-destructive, and openWorld. The description adds the salient behavioral trait that the key is not persisted, which matters for a credential tool. It doesn't mention rate limits or error semantics, 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?

Two tight sentences with the non-persistence constraint and the routing guidance front-loaded. Zero waste.

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

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

An output schema exists so return values need no explanation, and the when-to-use is fully covered. But with a 0% schema coverage on two required params, the definition leaves the provider/format ambiguity unaddressed.

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 for the two required parameters. It says nothing about what provider values are accepted (no enum, no list_llm_providers reference) or the api_key format, so an agent has to guess.

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 (test) and resource (LLM provider key) plus the key scope constraint (without storing it). The agent can distinguish it from set_llm_key immediately.

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

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

Explicitly names the alternative (set_llm_key) and the condition that selects it (checking validity first). This is the textbook when-to-use guidance.

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