Oi

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

Beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description adds a safety guarantee: 'Does not return access tokens, refresh tokens, or secrets.' It also states the current plan, exact limits, and a directive on what to do when work exceeds the plan, providing rich behavioral context for the agent.

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 core purpose, use cases, and security note are front-loaded, followed by a structured '## Plan and Billing' section. It is somewhat verbose with a long list of static limits that could go stale, but the section is organized and relevant to the tool's purpose.

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

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

For a zero-parameter read-only introspection tool with an output schema, the description covers purpose, triggering conditions, security exclusions, plan/limit context, and the billing link. Nothing needed for an agent to call it correctly is missing.

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

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

The input schema has zero parameters and 100% schema description coverage, so no parameter semantics are needed. Per the baseline rule for 0-param tools, a 4 is appropriate; the description adds no param-specific detail because none exists.

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 specific verb and resource: 'Return the current Oi MCP authentication, organization context, billing plan, current limits, and billing link for debugging.' This both states an exact action and scopes the tool to a unique resource, clearly distinguishing it from the many sibling tools focused on skills, guardrails, or contexts.

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 enumerates triggering user intents: 'who Oi is authenticated as, which organization this MCP session is using, what plan or limits apply, or why Codex/ChatGPT may be seeing different Oi data.' This gives an agent concrete conditions for selection without needing to infer from the name or title.

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 are minimal (no readOnly, no destructive flags), so the description carries the behavioral burden and fully delivers. It discloses the confirmation flow (Oi returns a prompt and saveArguments), the AI markdown update-pass mechanics (preserve structure, create headings, smallest accurate edit), response shapes (saved vs no-change), and a blacklist of content that must never be saved.

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 dense — every sentence earns its place for a 9-parameter tool with a subtle confirmation flow. It is front-loaded with the core purpose and trigger phrases, then flows naturally through exclusions, scope selection, behavioral mechanics, and negative constraints without 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 — dual propose/save modes, three scopes, confirmation semantics, and sibling surfaces — the description is complete. It covers when to call, how to set the two pivotal parameters, what the update pass will do, what responses to expect, and what content to refuse. An output schema exists, so return-value documentation is already handled elsewhere.

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, but the description adds genuine semantic value for the key parameters: it explains the interaction between scope and confirmed, gives concrete decision criteria for each scope enum, and describes what confirmed=true triggers (the markdown update pass). The provenance parameters (model, runtime, provider) and optional fields (reason, scopeReason) are left to the schema, which is acceptable.

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 verb-resource pair, 'Propose or save a direct durable update into Org Brain or User Brain,' and gives concrete trigger phrases ('update our org brain,' 'remember this for the organization'). It further distinguishes itself from sibling surfaces by explicitly excluding Contexts and Workflows unless the user asks for them.

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

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

The description is explicit about when to use this tool and how to vary its behavior: scope=auto with confirmed=false for unconfirmed durable memories, scope=organization for org-wide facts/policies, and scope=user for personal preferences. It names the alternatives to avoid (Contexts, Workflows) and gives a clear condition for invoking them instead.

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 tool read-only, idempotent, and non-destructive. The description adds meaningful context beyond those flags by disclosing that the returned capabilities are dynamic and that new provider actions do not require republishing MCP tools – a key behavioral trait for agents deciding whether to cache or re-query. No contradiction with annotations.

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

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

Two sentences with no filler. The core action and scope are front-loaded, and the second sentence justifies the tool's existence by explaining the dynamic behavior. 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?

For a low-complexity read-only getter, the combination of schema (100% parameter coverage), output schema, and annotations makes the definition complete. The description contributes the missing conceptual context – why capability data is live – so an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already fully documents provider and connectionInstanceId. The description adds no parameter-specific meaning beyond referring to 'one installed Connection', which is already captured by the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Return'), a precise resource ('live capabilities and input contracts'), and a scope ('one installed Connection'). The second sentence further distinguishes it from static/published tool definitions by emphasizing the dynamic nature of capabilities, which separates it from siblings like list and use.

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 implies the tool is used to fetch live capabilities and input contracts, and hints that it should be consulted instead of relying on published MCP tools when provider actions evolve. However, it does not explicitly state when to prefer this over oi.connections.list or oi.connections.use, nor does it provide exclusion 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?

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful context beyond those hints: it emphasizes schema stability and positions the tool as safe for discovery, adding value for an agent planning a workflow.

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

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

Two tight sentences with no filler. The purpose is front-loaded, and the stability/usage guidance is included efficiently. Every clause earns its place.

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

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

With an output schema present, annotations covering safety, and full parameter descriptions in the schema, the description supplies the remaining needed context: purpose, discovery role, and schema stability. Nothing an agent needs to call this tool 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 provides 100% description coverage for limit, cursor, and provider, so the description does not need to repeat parameter details. It adds no parameter-specific meaning beyond what the schema provides, matching the baseline for high schema coverage.

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 ('List'), a resource ('Connections'), and a scope ('current Oi organization'), clearly identifying the tool's function. It also distinguishes it from sibling tools by framing it as a 'stable discovery tool' used before selecting a provider or connection instance.

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 context: use this tool before selecting a provider or connection instance. It does not name sibling alternatives or state when not to use oi.connections.get/use, but the timing guidance is clear enough for an agent to decide.

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

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=true, openWorldHint=true) by disclosing credential resolution, organization policy application, write-target verification, confirmation requirement for writes, execution auditing, and protection of provider secrets. These behaviors are consistent with the destructiveHint annotation and give an agent actionable expectations, such as a confirmation step before external writes. No contradiction.

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 with no filler. The first sentence front-loads the purpose and required inputs; the second compacts a dense set of behavioral guarantees into one readable clause chain. 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?

For a complex dynamic-action tool with 7 parameters, nested batch targets, and a write-confirmation flow, the description covers the essential workflow and critical runtime behaviors (policy, confirmation, audit, secret safety). The remaining details, such as the batch exclusion rule and endpointKey handling, are already fully documented in the schema, and an output schema exists, so nothing mission-critical is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; each of the 7 parameters already has a meaningful schema description, including the batch-versus-single-target exclusion and the confirmed flag semantics. The description adds only marginal context (why secrets aren't passed, why confirmation matters) and does not attempt to document individual parameters — appropriate given the schema carries that 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?

States a specific verb plus resource: 'Execute a capability returned by Connections Get.' This differentiates it from siblings like oi.connections.get (which returns capabilities) and oi.connections.list (which lists providers/instances). The phrase 'Pass the provider, dynamic action name, and its arguments' makes the operation concrete.

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?

Establishes a clear workflow: obtain a capability via Connections Get, then execute it here. The provider selection from Connections List is also implied in the schema and description. However, it never explicitly names exclusions or contrasts with other 'use' siblings (oi.skills.use, oi.workflows.use, oi.contexts.use), leaving formal when-not-to-use guidance absent.

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 description adds meaningful behavioral detail beyond the annotations: creation defaults to a private draft, `publish: true` releases and publishes publicly, and `privateContent` is for organization-private instructions. The annotations already indicate a write operation, and the description does not contradict them.

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

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

The core behavior is front-loaded and well structured, but the 'Plan and Billing' section is generic boilerplate that adds length and distracts from the tool-specific guidance. It is organized, but not every sentence earns its place in a tool definition.

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

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

For a tool with 17 parameters, the description provides the essential creation lifecycle context, licensing conditions, and private/public distinction. Since an output schema exists, return-value documentation is not required, and the description covers the main decisions an agent needs to make when calling this tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra value by distinguishing `content` as markdown body versus `privateContent` as non-published private instructions, and by explaining the `publish` parameter's effect on the initial draft.

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 specific verb and resource: 'Create an Oi Context in the current organization.' It further clarifies the default behavior (private draft) and the publish option, which distinguishes this creation action from sibling tools like update, get, or use.

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 explicitly says to use this tool 'only when the user explicitly asks to create or import a Context' and requires confirmation that the source license permits reuse. This gives strong when-to-use guidance, though it does not explicitly name alternative sibling tools for comparison.

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 description makes the primary behavior clear: it returns a compiled prompt. However, all annotations are false, so there is no disclosed safety profile, and the description does not mention whether invoking this tool has any side effects, usage tracking, or auth implications. It is not contradictory, but it adds only modest behavioral context beyond the schema.

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

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

Two sentences with no filler: the first states the tool's purpose, and the second provides routing guidance. The most important 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 single-parameter tool with a full output schema, the description plus schema gives an agent enough to select and invoke the tool correctly. The sibling routing guidance and the schema's parameter documentation cover the essential context.

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 sole parameter contextId is already fully documented in the schema with 100% coverage. The description does not add selector syntax, version-pin details, or multi-context behavior beyond what the schema already states, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Return the reusable compiled prompt for a specific Oi Context.' It also distinguishes itself from oi.contexts.use, so an agent can tell this tool apart from its closest sibling.

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

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

It explicitly says to prefer oi.contexts.use when a concrete task already exists, giving a clear selection rule between get and use. This is direct, actionable guidance rather than leaving the choice to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, which covers the safety profile. The description adds valuable behavioral context: it returns at most 10 records, is not exhaustive, and is scoped to the organization. This goes beyond what the annotations alone communicate.

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 first paragraph is tight and front-loaded with the core purpose and routing guidance. However, the large 'Plan and Billing' section is generic, mostly unrelated to invoking this list tool, and adds considerable length; it likely appears across many tools and dilutes the tool-specific description.

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?

The tool is simple, has no required parameters, a rich output schema, and annotations covering safety. The description adds the key missing behavioral details: pagination limit, non-exhaustiveness, and when to route to oi.contexts.use instead. It is complete enough for an agent to call the tool correctly, though it omits any guidance about oi.contexts.search.

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?

Parameter schema coverage is 100%, with both 'text' and 'query' already documented in the input schema. The description adds no additional parameter-level meaning beyond recognizing 'text' as an alias for 'query,' so it does not meaningfully compensate or improve on the schema.

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

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

The description clearly states a specific action ('List a paginated preview of Oi Contexts available to this organization') and ties it to common invocation phrases like 'oi list contexts.' It also distinguishes itself from oi.contexts.use by saying direct context/selector requests should go there, though it does not explicitly differentiate from the sibling oi.contexts.search.

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 (primary listing tool for list-style requests), and explicitly says not to use it to pre-validate existence when a named context or selector is given, routing to oi.contexts.use instead. It does not mention oi.contexts.search as an alternative for more exhaustive discovery, leaving a small gap.

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?

Despite annotations covering the basic safety profile, the description adds substantial behavioral detail: where data lands (Private under subheadings when runtime updates are enabled), what is preserved (structured metadata like suggested prompts, categories, tags), what could change it (another structured write path), and the confirmation gate. This goes well beyond what readOnlyHint/destructiveHint convey and gives the agent a realistic model of the write behavior.

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

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

The description is long but dense, with every sentence earning its place: core action, exclusions, optional runtime behavior, metadata preservation, confirmation requirement, and content restrictions each occupy one distinct sentence. The core action is front-loaded in the first sentence, and while there is some redundancy in the confirmation requirement (mentioned in both description and schema), the efficiency is strong given the guidance load.

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 complex write tool with 7 parameters, the description is complete: it covers intended use, exclusions, data placement, preservation semantics, confirmation requirements, and sensitive-content prohibitions. The output schema exists so return values need not be described, and nothing an agent needs to decide whether and how to invoke this tool is missing.

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

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

Schema coverage is 100%, setting a baseline of 3, and the description does add value beyond the schema: it clarifies that contextId must be the latest mutable draft, that feedback must represent durable repeated corrections rather than one-off details, and reinforces the confirmed gate. The description frames the intended use of the parameters even though it doesn't describe each parameter's syntax.

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 first sentence states a specific verb (save), resource (active private Context draft), and scope (single latest Context), clearly distinguishing it from the sibling oi.brain.save-feedback. It further differentiates itself by explicitly excluding multi-context selectors and version-pinned Contexts, so an agent can tell it apart from the broader contexts family without opening 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 explicit when-to-use and when-not-to-use guidance: only after user confirmation, only for repeated corrections or updated logic, never for one-off details, temporary debugging, secrets, or credentials. It also names exclusions (multi-context selectors, version-pinned Contexts) and notes an alternative path for structured metadata updates, leaving little to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations by explaining result ordering: organization/private results first, then public marketplace results. This helps the agent set expectations about the returned set.

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

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

The tool-specific first paragraph is tight and front-loaded, but the large 'Plan and Billing' section is unrelated boilerplate that does not help an agent invoke this specific search tool. It adds significant length without earning its place in this tool's definition.

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

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

For a simple read-only search with two documented parameters and an output schema, the description covers semantics, result ordering, and the intended discovery scenario. The billing section is irrelevant but does not create a functional gap in the agent's ability to call the tool 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 100% and both query and limit have descriptions in the schema. The description adds value by clarifying what the query can target (need, title, tag, category, or organization) and by explaining the global search path, which informs how results are ranked/filled.

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 ('Search'), a resource ('Contexts'), and search dimensions ('need, title, tag, category, or organization'). It also distinguishes itself from plain list/get tools by describing the app-global search path and marketplace result inclusion, so an agent can tell it apart from siblings like oi.contexts.list.

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 a clear trigger: 'Use this when the user is unsure which Context exists or wants to discover a Context before creating a Workflow.' It does not explicitly name alternative tools or exclusion criteria, but the intended scenario is concrete enough to guide selection.

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 only mark the operation as not read-only, not open-world, and not destructive. The description adds the session-scope ('for the current client thread'), the reserved-selector stripping rule, and the output behavior ('compiled context text only, with no user task attached'), which meaningfully exceeds 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?

Three sentences, each earning its place: core action, input caveat, return behavior. No redundancy or 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?

The definition is complete for a single-parameter tool with an output schema. It covers what is loaded, the scope, input formatting, and output type. Minor gaps like session replacement semantics are not needed 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 the practical rule that ctx/context/contexts are reserved type selectors, not IDs, and directs the agent to strip them before passing, which goes beyond the schema's 'Raw Context selector' phrasing.

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 specific verb and resource: 'Load one or more Oi Contexts as reusable session context for the current client thread.' It also specifies the return shape ('compiled context text only, with no user task attached'), which distinguishes it from other context tools that may attach tasks or fetch raw contexts.

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

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

The description provides a clear use case (loading reusable session context) and a caution about reserved selectors, but it never names sibling tools or states when to prefer this over oi.contexts.use, get, or workflows.start-session. Usage context is implied rather than explicit.

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

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

Annotations only convey readOnlyHint=false, destructiveHint=false, and openWorldHint=false. The description adds meaningful behavioral context: the tool updates a private draft, operates in the current organization, includes license metadata, and can release the updated draft. It also communicates plan limits and the instruction not to invent exceptions, which is useful agent-facing behavior.

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

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

The first sentence is concise and front-loaded with tool-specific purpose. However, the large 'Plan and Billing' block is boilerplate policy that is not specific to this tool and adds length, even though it may be operationally valuable in the broader agent context.

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 (17 params, one required), the description covers the essential lifecycle behavior (draft update and release), scoping to the current organization, and plan constraints. An output schema exists, so return values need not be described. It lacks explicit partial-update/merge semantics, but the description is sufficiently complete for 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 all 17 parameters already have descriptive meaning. The description adds emphasis on license metadata and the release action but does not provide deeper semantics beyond what the schema already states. This aligns with the baseline of 3.

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

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

The description opens with a specific verb and resource: 'Update an existing private Oi Context draft in the current organization.' It also defines the special action=release state transition, which clearly distinguishes this tool from sibling tools like oi.contexts.create, oi.contexts.get, and oi.contexts.list.

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 indicates when to use this tool: when updating an existing private draft, with optional release via action=release. It also warns against multi-context selectors in the contextId parameter. However, it does not explicitly name alternatives or say 'use create for new contexts,' so it stops short of full when/when-not 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 are all false and thus provide no safety signal, so the description carries the full behavioral burden. It discloses that the tool returns an execution-ready prompt with the request appended under ## User Request, and details plan/billing behavior including doing the available portion, stating what is blocked, and including the billing link. This goes well beyond the schema and 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?

The tool's purpose and key routing rules are front-loaded in the first lines, and the selector guidance is dense but necessary. However, the Plan and Billing section includes exact numeric limits and a billing URL that are not needed for selecting or invoking the tool, making the description longer than strictly necessary.

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 tool with complex selector syntax and several sibling use tools, the description covers the main edge cases: multi-context, version pins, reserved selectors, implicit routing, and workflows as an alternative. It even describes the return format and plan-related behavior, so nothing an agent needs to call it correctly is missing.

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

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

Although the schema already documents both parameters with 100% coverage, the description adds critical selector syntax: raw selectors passed unchanged, + multi-context selectors up to 3, @2/@v2 version pins, and a concrete example. It also warns to strip reserved selectors (ctx/context/contexts) and never treat a missing list preview as absent, materially improving parameter understanding.

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 'Use Oi Contexts for a concrete task' and provides concrete request examples, clearly identifying the tool as the primary Context execution path. It also distinguishes itself from Workflow routing by reserving workflow/wf selectors for the Workflow path, so an agent can tell it apart from sibling tools like oi.workflows.use.

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 states this is the primary tool for named request patterns and instructs the agent to strip reserved Context selectors while routing workflow selectors to the Workflow path. It also tells the agent not to list contexts first and explains that omitting contextId triggers implicit routing, making the when-to-use and when-not-to-use boundaries 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?

Annotations are sparse (only non-read-only and non-destructive), so the description carries the transparency burden. It adds genuinely useful behavioral guidance — preferring usageEventId over traceId, and requiring redacted summaries — but it never states the call's side effects, whether it is a one-way fire-and-forget telemetry send, or anything about failure or rate-limit behavior.

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

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

Four sentences with the purpose front-loaded and zero filler. Every sentence earns its place, though there is minor redundancy between the opening purpose and the second sentence which restates the after-task-completion timing.

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 an 11-parameter tool with sparse annotations, the description covers core usage timing, ID selection, and content safety well. But it gives no guidance on which optional parameter groups (outcome vs actions vs userFeedback vs confidence) are meant to be sent together, and it never explains what the system does with the report. The output schema mitigates the return-value 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?

With schema description coverage at 55%, the description adds real value for usageEventId (preference), traceId (fallback), and taskSummary (redaction rule). However, its outcome list ('accepted, retried, saved, copied, completed, or rejected') blends outcome enum values with action enum values, which could mislead an agent into sending invalid values to the outcome field, and baselineMode/confidence get no clarification beyond their enums.

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 specific verb and resource — 'Report what happened after an Oi-assisted task completed' — and enumerates the outcome states it covers (accepted, retried, saved, copied, completed, rejected). This clearly differentiates it from the closest sibling oi.usage.report, which is about usage metrics rather than task effectiveness.

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 explicitly states when to call it ('Use this after calling an Oi Context, Workflow, Skill, Connection, or Guardrail tool when you know whether the result was accepted...') and imposes content restrictions ('Do not send raw prompt text'). It falls short of 5 because it never names alternatives or states when NOT to use it in favor of oi.usage.report or the feedback tools.

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

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

Annotations (readOnlyHint=false, destructiveHint=false) carry little information on their own, and the description adds useful context: confirming causes the blocked request to continue, and the requestId embeds original routing details. It does not disclose idempotency, whether the confirmation is one-time or persistent (apart from the remember flag documented in schema), or what happens with a stale/invalid requestId.

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 with no wasted words. The verb and object are front-loaded, and the second sentence earns its place by explaining the significance of the key parameter. Nothing repeats the schema or annotations.

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

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

For a two-parameter tool with full schema coverage, an output schema, and annotations present, the description covers the essential scenario (post-trigger confirmation) and the role of the required parameter. Minor gaps remain about what 'continue' concretely entails and whether confirmation is reversible or one-time, but nothing blocks 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 genuine meaning beyond the schema by explaining that requestId 'carries the original Context or Workflow routing details', clarifying why confirming resumes the original request — value the schema's field description does not provide.

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 ('Confirm') on a specific resource ('a triggered Oi Guardrail') and defines the triggering scenario ('blocked Context or Workflow request and continue'). This clearly distinguishes it from sibling guardrail tools like create/update/delete/list/publish/unpublish, which handle lifecycle management rather than approving a triggered block.

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 usage context is clear: call this after a guardrail has triggered and blocked a request, with the requestId coming from that prior warning (also reflected in the schema). However, it does not explicitly name alternatives or state when-not-to-use, though the difference from lifecycle siblings is easy to infer.

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, destructiveHint=false) establish that this is a mutation. The description adds context beyond that: creation defaults to a private draft, publish:true releases v1 and makes it public, and there is a license-reuse restriction. No contradiction with 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?

Four sentences, each earning its place: purpose/scope, default behavior, explicit usage gate, and content preference. The most decision-relevant facts are front-loaded in the first two sentences with zero 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?

Given an 11-parameter tool with an output schema and annotations, the description covers the key decisions: draft vs published, license gating, and content preference. It could additionally contrast publish vs release timing or route follow-up edits to update, but nothing essential for a first call is missing.

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

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

Schema coverage is 100%, so the schema already documents all 11 parameters including the publish parameter's meaning. The description adds modest value with "Prefer markdown content in content," reinforcing the schema's own "Prefer content for new writes" note, but does not materially expand parameter understanding beyond the baseline.

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

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

"Create an Oi Guardrail in the current organization" names a specific verb, resource, and scope. The default-private-draft behavior and the publish flag implicitly separate this from sibling publish/release tools, so an agent can tell what this tool does 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?

"Use this only when the user explicitly asks to create or import a Guardrail and the source license permits reuse" is an explicit when/when-not gate with a licensing condition. It does not name a specific alternative tool (e.g., update for edits), which keeps it from a 5.

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

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

Annotations already signal destructiveHint=true, and the description adds valuable nuance by saying 'Archive and disable' and 'This is not a physical database delete.' This clarifies the actual consequence beyond the raw destructive flag. It does not fully disclose prerequisites like permissions or reversibility, but the annotation coverage lowers the burden.

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 two short sentences with no filler. The primary action is front-loaded, and the clarifying note about not being a physical database delete earns its place by preventing a common misconception.

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

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

For a single-parameter tool with an output schema and annotations already marking the operation as destructive, the description is nearly complete. It defines scope, effect, and a key non-behavior. A minor gap is the absence of any statement about prerequisites or restrictions around published/active guardrails, but the overall context is sufficient 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%, and the only parameter, guardrailId, is already described as 'Guardrail id to archive.' The tool description does not add any further meaning to the parameter beyond repeating the archive concept, so the schema carries the load. Baseline 3 is appropriate.

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

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

The description uses a specific verb-resource pair: 'Archive and disable a private Oi Guardrail in the current organization.' It also clarifies the scope ('current organization') and explicitly distinguishes the operation from a permanent delete, which helps disambiguate it from other guardrail lifecycle tools like unpublish or update.

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 implies that this tool is for archiving/disabling a private guardrail in the current org, but it does not explicitly state when to use it versus alternatives, nor does it mention exclusions such as published guardrails requiring unpublish first. The context is clear enough to infer basic usage, but explicit routing guidance is absent.

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 (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description only needed to add context beyond that. It adds the org-scoping constraint ('for the current organization') and the 'private' visibility qualifier, which meaningfully inform the caller about what kind of record is returned. It does not disclose failure behavior for missing records, but with annotations present this is 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?

One sentence, front-loaded with the action verb, with every phrase earning its place: 'private' signals visibility, 'for the current organization' signals scope. No filler or repetition of schema content.

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 single-parameter read operation with a full output schema and complete annotations, the description covers the essential contract: what it returns, the scope, and the record type. The main residual ambiguity — what 'private' means in the guardrail lifecycle and which sibling to fall back to — is a modest gap given the low 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 100% — the single parameter guardrailId is already documented as 'Guardrail id or slug to load' in the schema. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

The description uses a specific verb ('Return') plus a resource ('private Oi Guardrail record') and a scope ('for the current organization'), making the core function immediately clear. The qualifier 'private' hints at a distinction from sibling operations like list or publish, but the description never names a sibling explicitly, so it stops short of full differentiation.

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 usage context is implied: call this when you need a single guardrail record by id or slug within the current organization. However, it provides no explicit guidance on when not to use it or which alternative to choose — for example, no mention that oi.guardrails.list enumerates guardrails or that confirm/publish handle lifecycle actions.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond those hints: results are paginated, limited to private guardrails, and scoped to the current organization. No annotation contradiction 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?

A single sentence states the operation, scope, and pagination behavior with no filler. The most decision-relevant information is front-loaded, making it easy for an agent to process quickly.

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

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

For a zero-parameter, read-only list operation with an output schema, the description tells the agent exactly what the call will do and what scope it covers. Omitted details such as page size or exact response shape are not required to invoke the tool 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?

The input schema has zero parameters and full documentation coverage, so the description carries no parameter burden. There is nothing to describe, so the baseline for a zero-parameter tool applies.

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

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

The description names a specific operation (List), the resource (private Oi Guardrails), and the scope (current organization), going beyond the title with 'paginated preview.' This clearly distinguishes it from oi.guardrails.get and the mutation tools in the sibling set.

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 implies the tool is for browsing or previewing guardrails in the current organization, and the sibling set makes the alternative operations visible. However, it does not explicitly state when to prefer this over oi.guardrails.get or when not to use it, so usage guidance remains implicit rather than explicit.

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

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

Annotations already establish that this is a non-read-only, non-destructive operation (readOnlyHint=false, destructiveHint=false). The description adds contextual scope ('private', 'current organization') but does not disclose what publishing actually changes, such as visibility, access permissions, or reversibility. Given the annotations carry the safety profile, the description adds only minor behavioral context.

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

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

The description is a single front-loaded sentence with no filler. Every word contributes meaning, and it is appropriately sized for a tool with one parameter.

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 one-parameter mutation with an output schema and annotations covering safety, the description is largely sufficient. However, it does not clarify how publishing differs from the sibling release/unpublish tools, which could lead to incorrect tool selection in lifecycle-related workflows.

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%, with the sole parameter guardrailId already described as 'Guardrail id to publish.' The description does not add any extra meaning beyond the schema, 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?

The description uses a specific verb ('publish'), a resource ('private Oi Guardrail'), and a scope ('current organization'), which clearly communicates the core action. It does not explicitly distinguish itself from sibling tools like oi.guardrails.release or oi.guardrails.unpublish, but the 'private' qualifier implies a state transition that contrasts with unpublish.

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 offers no guidance on when to use this tool versus alternatives such as release, unpublish, or confirm. It provides no exclusions, prerequisites, or context about the guardrail lifecycle, leaving an agent to infer usage entirely.

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 say the operation is not read-only and not destructive, but the description adds little beyond that. It does not explain what 'release' changes, whether it affects visibility, or whether the action is reversible.

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

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

The description is a single, front-loaded sentence with no redundant wording. It could earn a higher score by including a clarifying clause about what releasing entails, but it is appropriately concise for a one-parameter 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?

The tool has an output schema and simple parameters, so return-value detail is not required. However, the core meaning of 'release' remains ambiguous in a domain that also has publish and unpublish siblings, leaving an agent without enough context to invoke it correctly.

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

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

The schema already fully documents the single parameter with a description ('Guardrail id to release'). The tool description does not add extra parameter context, so it meets the baseline for high schema coverage.

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

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

The description states a clear action ('Release'), a specific resource ('private Oi Guardrail'), and a scope ('current organization'). It is not a bare restatement of the title, but it does not explicitly distinguish 'release' from sibling operations like publish or unpublish.

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

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

No when-to-use or when-not-to-use guidance is provided. The word 'private' implies the tool applies to private guardrails, but the description never tells the agent to prefer publish, unpublish, or another sibling for different lifecycle states.

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 mark this as non-readonly and destructive, and the description is consistent with that; no contradiction exists. It adds minor scope context ('private', 'current organization') but does not disclose effects such as reversibility or what happens to previously published versions.

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 declarative sentence that front-loads the action and scope with no filler. Every word earns its place.

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

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

For a one-parameter tool with full schema coverage, an output schema, and destructive annotations, the description is largely sufficient. The main gap is not explaining its relationship to publish/release/delete, but that is not required for basic 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% and the schema already describes guardrailId as 'Guardrail id to unpublish.' The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

The description clearly names the operation ('Unpublish'), the resource ('a private Oi Guardrail'), and the scope ('current organization'). It is not a tautology and is semantically distinct from publish and delete, though it does not explicitly differentiate itself from the sibling release 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?

The phrase 'private ... in the current organization' implies the target condition and scope, but the description never states when to prefer this over oi.guardrails.release, oi.guardrails.delete, or oi.guardrails.publish. There is no explicit when/when-not 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 mark this as non-read-only and non-destructive, and the description adds meaningful side-effect detail: draft versioning and publish-first release behavior. It does not discuss permissions, idempotency, or failure modes, but the most important behavioral nuances are disclosed.

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 two concise sentences with the main action and key behavioral rules front-loaded. It contains no filler and every sentence adds meaningful 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 an 11-parameter write operation, the description plus full schema coverage and output schema covers the essential decisions an agent needs to make. The non-obvious behaviors—draft versioning and publish precedence—are stated. Some additional lifecycle context could be helpful, but nothing critical is missing given the annotations and schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a useful clarification beyond the schema by noting that `publish: true` releases the draft first, which is not explicit in the parameter description. Other parameters are already well documented in the schema, so the description does not need to repeat them.

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 action: 'Save changes to a Guardrail draft.' It also clarifies the core versioning behavior: update the open draft or create the next draft version. This clearly differentiates it from generic update tools and from sibling publish/release 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?

The description gives a clear behavioral condition: if an open draft exists it updates it, otherwise it creates the next draft version. It also explains the `publish: true` side effect, which helps the agent decide when to release. It does not explicitly name sibling alternatives or state when not to use this tool, but the context 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?

The phrase 'before running it' clarifies that the tool recommends rather than executes, which is meaningful behavioral context. Annotations already indicate readOnly, idempotent, and non-destructive behavior, so the description supplements rather than contradicts them.

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

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

Two concise sentences: the first states the core function and the second gives the triggering usage. There is no filler or repetitive phrasing.

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, single-parameter, read-only recommendation tool, the description is complete. The output schema covers return details, annotations cover safety, and the description provides purpose and usage context.

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

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

Schema description coverage is 100%, with the prompt parameter already documented as the task/request to match against installed Contexts and Workflows. The tool description adds little beyond that, so it meets the baseline without significantly enriching parameter meaning.

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 a specific action ('Recommend') and a specific resource ('best Oi Context or Workflow for a prompt'). It is clear about what the tool does, though it does not explicitly distinguish itself from related search/use siblings such as oi.contexts.search or oi.workflows.use.

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 a direct when-to-use condition: when the user asks 'oi recommend' or wants help choosing the most suitable reusable setup. It does not list when-not-to-use or explicitly name alternatives, but the intended context 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?

Beyond the annotations, the description discloses that the skill starts as a private draft, that `publish: true` also releases the initial version, and that plan limits constrain what the agent can do. It adds concrete billing and fallback instructions that are not present in the schema or annotations, and it does not contradict any annotation.

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 core behavior is front-loaded in the first sentence, and the plan/billing content is separated under its own heading. However, the limits list is verbose and includes many values not directly relevant to skill creation, so the description is not maximally tight.

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 a rich input schema, an output schema, and annotations, the description covers the essential behavioral nuances and the plan context that can block creation. It could be more complete by explicitly routing to sibling tools for update/publish operations, but an agent has enough information to call the tool 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?

The input schema already covers all 11 parameters, so the baseline is 3. The description adds meaning by explaining the interaction between `publish`, `release`, and the private-draft default, which is not fully obvious from the individual parameter descriptions. The remaining parameters are well documented by the 100% schema coverage.

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 specific action: 'Create an Oi Skill in the current organization' and immediately clarifies the default lifecycle state, a private draft. This makes the resource and verb unmistakable and distinguishes it from siblings like oi.skills.get, oi.skills.list, oi.skills.update, and oi.skills.publish.

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 context for when to use the tool: creating a new skill, with the option to publish immediately via `publish: true`. It implies that updating or publishing existing skills belongs to sibling tools, though it does not explicitly name alternatives such as oi.skills.update or oi.skills.publish.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful context beyond that: the return value is an 'execution-ready reusable instruction document' and the tool deliberately does 'not append a task,' which clarifies how it differs from the execution-oriented sibling. No contradiction with annotations.

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

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

Two sentences with zero waste: the first defines the core function, the second provides the critical routing rule. The distinguishing behavior ('without appending a task') is front-loaded before the alternative is mentioned.

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

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

For a single-parameter read-only get tool, everything needed is present: purpose, routing guidance, and the safety profile come from annotations. An output schema exists, so the description needn't explain return values. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100% — the schema already documents skillId as 'Skill id or slug to load.' The description adds no parameter-level detail, so the baseline of 3 applies; the schema carries the full burden and does so adequately.

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 ('Return') and resource ('an installed Oi Skill'), and characterizes the result precisely: 'execution-ready reusable instruction document without appending a task.' It explicitly differentiates from the sibling oi.skills.use by noting the task-append distinction, so an agent can tell them apart without opening 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 second sentence gives explicit routing guidance: 'Prefer Use Skill when the user has a concrete task.' This names the alternative and states the condition that selects it, which is exactly the key decision point for an agent choosing between get and use. Minimal but sufficient.

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 mark the tool read-only, idempotent, and non-destructive; the description adds that results are a paginated preview scoped to the organization, and includes explicit plan/billing behavior. This is useful context beyond the annotations and does not contradict them.

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

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

The first two sentences are sharp and front-loaded, but the large Plan and Billing section is generic boilerplate unrelated to the mechanics of listing skills. The description carries far more non-tool content than tool-specific content.

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 read-only list with two optional parameters and an output schema, the description covers scope, pagination, and plan-related behavior. Nothing essential for calling the tool correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description adds no additional parameter meaning, which is acceptable given the baseline.

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

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

The description opens with a specific verb ('List'), a concrete resource ('Oi Skills'), and a scope ('available to this organization'), plus 'paginated preview' that distinguishes it from get/search siblings. An agent can tell this is the enumeration operation for organization-scoped skills.

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 phrasing implies use when an agent needs an overview of available skills, but there is no explicit guidance on when to prefer this tool over oi.skills.search or oi.skills.get. The billing block provides plan-behavior instructions, not tool-selection 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?

The description adds the 'released' prerequisite and marketplace context, which aligns with annotations (readOnlyHint=false, openWorldHint=true). It does not disclose additional behavioral details such as whether publishing is irreversible, whether it updates an existing published listing, or any visibility/availability side effects. Given annotations already convey mutation and non-destructiveness, the description partially supplements them.

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

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

The description is a single, concise sentence with no filler or redundant phrasing. The key action ('Publish') is front-loaded, and all added terms (released, marketplace, current organization) earn their place by adding meaningful constraints.

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 one-parameter action tool, the description, combined with a complete input schema and helpful annotations, provides sufficient context for an agent to invoke it correctly. The main gap is that it does not clarify behavior when the skill is already published or how 'released' is determined, but the existing structured data covers most operational needs.

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

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

Schema description coverage is 100% for the single skillId parameter, which already explains 'Skill id or slug to publish.' The tool description does not add any additional meaning or constraints about the parameter beyond what the schema provides, so the baseline score 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?

The description uses a specific verb ('Publish') with a clear resource ('released Oi Skill'), target ('marketplace'), and scope ('for the current organization'). This distinguishes it from sibling tools like oi.guardrails.publish and other skill tools (create, update, use), so an agent can identify exactly what this tool does.

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

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

The word 'released' implies the skill must already be in a released state before publishing, which is an implicit usage condition. However, the description does not explicitly mention when not to use the tool, mention alternatives, or explain what to do if the skill is not released. Usage is inferred rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a useful scope detail—searching both installed and marketplace skills—but does not disclose additional behavior. The plan/billing paragraph is unrelated to tool behavior.

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

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

The first sentence is concise and front-loaded. However, a large unrelated plan-and-billing block about organization limits and upgrade URLs is appended, adding noise and distracting from the tool's purpose. This block does not help an agent call the search tool correctly.

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 simple two-parameter schema, rich annotations, and an output schema, the core description is complete enough: it explains what is searched and by which criteria. The extraneous billing paragraph is noise, but it does not leave a gap in the information needed to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents 'query' and 'limit' clearly. The description adds search facets (need, title, tag, category) that give the query parameter more semantic meaning, but it does not go beyond that baseline.

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

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

The first sentence states a specific action ('Search') on a specific resource ('installed and marketplace Skills') with search dimensions ('need, title, tag, or category'). It is clear enough to distinguish from list/get by indicating query-driven search, though it does not explicitly name sibling 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?

The description implies when to use the tool: when searching for skills by need, title, tag, or category across installed and marketplace sources. However, it does not explicitly state when to prefer search over oi.skills.list or oi.skills.get, nor does it give any exclusions.

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

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

Annotations only indicate readOnly=false and destructiveHint=false, so the description adds meaningful behavior by noting the draft scope and the release action. The long billing section is not tool behavior, but the core description provides useful mutation context without contradicting 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?

The opening sentences are clear and front-loaded, but the large 'Plan and Billing' section adds substantial unrelated boilerplate. This reduces conciseness, though the structure with a heading keeps it organized.

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 rich input schema and presence of an output schema, the description covers the core behavioral intent and the release workflow. It could be slightly stronger with explicit sibling exclusions, but nothing critical is missing for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds value beyond the schema by explaining the meaning of action=release, which is the most behaviorally significant 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?

The description clearly identifies the tool as 'Update an existing private Oi Skill draft' with a specific verb, resource, and scope, and it adds the key behavior 'Pass action=release to release the updated draft.' This gives an agent enough to distinguish it from create, publish, get, and search 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?

The description gives clear context: it is for updating an existing private draft, not creating or fetching. It also explains how to trigger a release via action=release. It does not explicitly name alternatives like oi.skills.create or oi.skills.publish, but the usage context is strong enough to guide selection.

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 description importantly reveals that the tool returns a prompt rather than directly executing the task, which is a key behavioral trait. However, annotations are all false (not read-only, not idempotent, etc.), so the description carries the burden of explaining side effects, permissions, or execution semantics, and it does not explicitly state that the skill is not executed.

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 concise sentences, with the core purpose front-loaded and no redundant filler. The description is appropriately sized for the tool's simplicity.

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 low-complexity tool with full schema coverage and an output schema, the description covers the essential purpose and return behavior. It is missing an explicit 'does not execute the skill' clarification and guidance on installed-skill prerequisites, but the 'execution-ready prompt' phrasing substantially mitigates that 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?

Since schema description coverage is 100%, the input schema already documents both parameters clearly. The description adds no additional semantics beyond aligning 'user request' with the prompt parameter, meeting the baseline but not exceeding 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 states a specific action ('Use an installed Oi Skill') and the concrete output ('Returns an execution-ready prompt containing the Skill document and user request'). This is clear and distinguishes the tool from management tools like get/list, but it does not explicitly differentiate it from similar sibling tools like contexts.use or workflows.use.

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 'for a concrete task' gives some usage context, and 'installed' implies a prerequisite. However, the description does not provide explicit when-to-use vs alternatives, nor does it mention what to do if the skill is not installed or when to prefer sibling tools like skills.get or skills.search.

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

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

With annotations already marking the tool as not read-only and not destructive, the description adds meaningful behavioral context: it does not store prompt text, and it clarifies that usageEventId is authoritative over optional identifiers. This goes beyond the structured annotations without contradicting them.

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

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

The description is two sentences with no redundancy. The core action and privacy guarantee are front-loaded, followed by precise parameter-priority guidance. 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?

Despite the tool having 18 parameters, the schema documents all of them, and an output schema is present. The description covers the non-obvious behavioral and selection details: attaching to a previously issued event, avoiding prompt text storage, and prioritizing usageEventId. Nothing essential is missing 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 extra meaning for the key parameter by explaining that usageEventId should come from a prior Oi tool result and is authoritative, while contextId/workflowId are only for client-side clarity. This is valuable semantic guidance beyond the schema.

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

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

The description clearly states a specific action (attach token accounting and runtime metadata) on a specific resource (previously issued Oi Context or Workflow usage event). It also adds a distinguishing privacy constraint ('without storing prompt text') and clarifies that usageEventId is authoritative, which helps differentiate it from reporting or effectiveness 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?

The description gives clear usage context: the tool should be used to augment an existing usage event using the usageEventId returned by a prior Oi tool result. It also explains the role of optional contextId/workflowId. It does not explicitly name alternatives or state when not to use this tool, but the guidance is strong enough for correct selection.

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 indicate a non-read-only, non-destructive mutation, and the description adds important behavior: the result is a private draft, not a released or published workflow. It also surfaces organization plan limits and directs agents to be transparent about plan-blocked capabilities, which is useful for setting expectations beyond the raw annotation flags.

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 opening sentences are front-loaded and efficient, but the Plan and Billing section contains a long list of unrelated limits such as seats, guardrails, skills, connections, API keys, and messages that do not directly help an agent use this create-workflow tool. The tool-specific content is concise, but the boilerplate reduces overall density.

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 17-parameter creation tool with full schema coverage and an output schema, the description covers the key contextual gaps: draft-only behavior, current organization scope, ordering of Context steps, and how to resolve uncertain Context ids. It does not explain duplicate-name handling or validation errors, but those are not essential given the schema's completeness.

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 17 parameters. The description adds little beyond noting that Context steps should be ordered and that Context ids or slugs are the relevant input, which mostly restates the schema's existing contexts field description.

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

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

The description states a specific verb and resource: 'Create a private Oi Workflow draft in the current organization'. It also distinguishes the tool's scope by clarifying that it creates a draft only and does not release or publish the Workflow, which is meaningful against sibling tools like oi.workflows.update and oi.workflows.use.

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 guidance to use oi.contexts.search first when unsure which Context ids or slugs to include. It also clarifies that this tool only creates a draft, implying release/publish is out of scope. It does not explicitly contrast with oi.workflows.update for modifications, but the usage context is clear enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safe-read nature is fully covered. The description adds only that the result is a 'compiled prompt scaffold', which is light behavioral context. There is no contradiction with annotations, but no deeper disclosure of error or caching behavior is provided.

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 with no filler. The primary action is front-loaded, and the sibling-routing guidance is placed second, making the description easy to parse at a glance.

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 one-parameter, read-only, idempotent getter with an output schema and explicit sibling guidance, nothing essential is missing. The description correctly orients an agent to when to call this tool and what to expect from the result.

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 has 100% coverage for the single workflowId parameter with a clear 'installed workflow identifier to load' description. The tool description repeats that it identifies by workflowId but adds no additional semantic detail beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Return'), names the exact resource ('reusable compiled prompt scaffold for a specific Oi workflow'), and identifies the key discriminator (workflowId). It is clearly distinguished from siblings like oi.workflows.list ('specific' vs collection) and oi.workflows.use ('scaffold' vs running a task).

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 routes to oi.workflows.use when the user has a concrete task, giving a clear when-not condition. The phrase 'by workflowId' also implies the tool is for fetching one known workflow rather than searching or listing, covering the main alternative.

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

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

Annotations already establish that this is a safe, idempotent read operation (readOnlyHint=true, destructiveHint=false, idempotentHint=true). The description adds useful context that results are scoped to the organization, but it does not cover output ordering, pagination, or other runtime behavior. This matches the expected baseline when annotations carry the safety profile.

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 two short sentences with no redundancy. It front-loads the core purpose and scope, then immediately gives actionable usage guidance. 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?

For a simple read-only listing tool with no required parameters, complete schema descriptions, safety annotations, and an output schema, this description provides sufficient context. An agent can select and invoke it correctly without missing critical information.

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

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

Schema description coverage is 100%, and both parameters (text and query) have clear descriptions in the schema. The tool description does not add parameter-level detail, but it does not need to because the schema already documents them adequately.

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 clearly states the action ('List') and the resource ('Oi workflows available to this organization'). It distinguishes this list tool from related workflow tools like get/use/start-session by focusing on enumeration rather than selection or execution.

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: when the user asks what workflows exist or mentions 'oi workflow/wf' without enough task detail. It implies that with sufficient task detail a more specific tool should be used, though it does not name alternatives explicitly.

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

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

The annotations are all false and therefore uninformative, so the description carries the behavioral burden. It clearly states the key side effect (loading into the current client thread session) and the exact return behavior ('compiled workflow context text only, with no user task attached'). It does not discuss session-overwrite semantics, but it does disclose the most important non-obvious behavior.

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

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

The description is three sentences with no filler. The core purpose is front-loaded, and the selector caveat and return behavior each earn their place. It is dense but still readable.

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 5-parameter session-start tool with a full schema and an output schema, the description covers what an agent needs to select and invoke it: what it loads, the session scope, the selector pitfall, and the return shape. Optional details like how existing session state is affected are omitted, but they are not required 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?

Input schema coverage is 100%, so the baseline is 3. The description adds value on top of the schema by explaining that workflowId must not be a reserved selector and must be the installed workflow identifier, preventing a common misuse. Other parameters remain documented by the schema, which is acceptable at full coverage.

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 specific verb-resource pair: 'Load a specific Oi workflow as reusable session context for the current client thread.' It also distinguishes the operation by noting that reserved selectors are not IDs and by stating the return is compiled context only with no user task attached, which separates it from execution-oriented workflow 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?

The description gives clear context for when to use the tool ('reusable session context for the current client thread') and includes a practical instruction to strip reserved wf/workflow/workflows selectors. It does not explicitly name alternative tools or provide when-not-to-use exclusions, so it falls just short of full 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 signal a mutating, non-destructive operation (readOnlyHint=false, destructiveHint=false), so the bar is lower. The description adds genuinely useful behavior beyond the annotations: full-replace semantics ('Send the complete draft shape'), the ordering requirement for Context steps, and the side-effect limitation that no release/publish occurs. No contradiction with 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?

The tool-specific portion is tight and front-loaded: three sentences covering the operation, the full-shape requirement, and the get-first guidance. The appended Plan and Billing section is generic organization boilerplate that is not tool-specific and adds roughly 100 tokens that do not help an agent select or invoke this tool correctly, preventing a 5.

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 an 18-parameter mutating tool, the description covers the operation scope, overwrite semantics, ordering requirement, and the draft-only boundary. With 100% schema coverage, an output schema, and annotations covering the safety profile, nothing critical is missing. A minor gap: it does not state what happens to omitted optional fields, though 'complete draft shape' strongly implies 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?

Schema description coverage is 100%, so the baseline is 3. The description adds value above the schema by warning that this is a complete-shape update, not a partial patch — telling the agent to include all fields and ordered Context steps, which affects how all parameters should be populated. This is meaningful guidance the field-level schema descriptions do not convey.

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 uses a specific verb and resource: 'Update an existing private Oi Workflow draft in the current organization by workflowId.' This clearly distinguishes it from siblings like oi.workflows.create (existing vs new), oi.workflows.get (mutation vs read), and any publish/release operation ('This updates the draft only; it does not release or publish').

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 instructs when to use a sibling instead: 'Use oi.workflows.get first if the agent needs to inspect the current workflow.' It also stakes out the tool's boundary by stating it updates the draft only and does not release/publish. It does not name a publish/release alternative explicitly, but the when-to-use guidance is clear and actionable.

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 description reveals useful behavior beyond the sparse annotations: Oi automatically selects the best installed workflow, reserved selector words are stripped, and the result is an execution-ready prompt with the user request under '## User Request'. It does not detail side effects or authorization requirements, which would have made it fully transparent, but it provides meaningful behavioral context.

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

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

Four focused sentences, each earning its place: primary use case, examples, workflowId guidance, selector warning, and return format. The most important operational detail is front-loaded. No filler or repetition.

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

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

Given the tool's complexity (six parameters, nested objects) the description plus 100% schema coverage and an output schema together provide enough to invoke it correctly. It explains the critical workflowId ambiguity and the output format, though it could have noted the relationship to workflow start-session/context execution siblings.

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, and the description adds extra semantics by explaining when to provide workflowId ('only for a specific workflow') and warning that wf/workflow/workflows are reserved selectors, not IDs. This clarifies the most error-prone parameter beyond the schema alone.

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 clearly identifies the tool as the primary path for concrete workflow tasks ('Use Oi Workflows for a concrete task') with concrete request examples. It is specific about verb and resource, but it does not directly contrast with sibling tools such as oi.workflows.start-session or oi.skills.use, so it earns a 4 rather than 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 clear usage context: use it for 'oi use ...' requests and either pass workflowId for a specific workflow or omit it for automatic selection. It also explains how to handle reserved selectors. It does not explicitly state when not to use the tool or name alternatives, so it stops short of a 5.

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