Ogen

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

With no annotations, the description carries the behavioral burden, and it does add non-obvious traits: 'Nothing is stored' signals statelessness, and 'Free and pro' hints at no paywall gating. It does not disclose the output format, failure behavior for malformed events, or how 'stale or uncertain' is determined. The 'Free and pro' line is low-signal filler.

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

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

Three short sentences, with the core behavior in the first sentence and the statelessness guarantee in the second. The final 'Free and pro' is marketing filler that does not help an agent invoke the tool correctly, so it slightly undermines the otherwise tight structure.

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, stateless analysis tool with no output schema, the description conveys the input (a log) and the gist of the output (a count of stale/uncertain actions), which is workable. But with no annotations or output schema, the agent is left to infer the exact return shape, error handling, and the criteria for 'stale or uncertain'. Some details live in the schema (ordering, ISO timestamps, item caps), so the overall picture is adequate rather than complete.

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 schema documenting the events array, its item fields (at, kind, acted, candidates, later_corrected), ordering, and the 2,000-item cap, so the baseline is 3. The description's 'log of your agent's past reads and actions' loosely maps to the events property but adds no per-field semantics beyond what the schema already provides. No compensation is needed, but no extra value is added either.

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 ('Paste... and see') and resource: a log of the agent's past reads and actions, and it defines the result as a count of actions that would have been taken on stale or uncertain data. This clearly conveys what the tool does and what it returns. It does not explicitly contrast with sibling tools, though the offline-log analysis purpose is fairly distinct from the live-operation 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 implies the usage context: an agent that has a log of past reads/actions and wants to know how many would have acted on stale or uncertain data. It offers the input format indirectly ('Paste a log of your agent's past reads and actions') but gives no explicit guidance on when to prefer this over related siblings like recall_live_fact or what_it_caught, and no exclusions.

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

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

With no annotations, the description carries the full burden, and it does disclose meaningful traits: the source is read-only, 'Every recall reads it fresh — nothing here is cached as truth' (freshness semantics), and 'Record only' (this registers a binding, it does not fetch). It stops short of stating auth/permission requirements or what happens when binding to an already-bound key, though the schema covers replacement and encryption-at-rest.

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?

Compact and front-loaded: the core action and its read-only, fresh-read nature lead, with the source enumeration following. The long comma-separated kind list is somewhat redundant with the schema enum but is defensible as a scannable summary.

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 no-output-schema configuration tool, the description plus the unusually detailed schema together cover the essentials — what binding does, source kinds, and the alongside/replace behavior. It could say more about what a successful bind returns or key-collision handling, but nothing 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 schema already documents key, url, field, source, headers, and alongside in rich detail. The description mostly restates the source-kind list that the schema's `kind` enum already carries, adding little parameter meaning beyond what is structured.

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 (bind) and resource (a key to a live, read-only source) and enumerates the full set of supported source kinds, so an agent knows exactly what operation is performed. It does not, however, name or contrast itself against the obvious sibling recall_live_fact, leaving the read/write-config distinction to inference.

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

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

Usage is only implied: 'Record only' and 'read-only source' suggest this configures a binding rather than reading data, which nudges the agent away from recall_live_fact. There is no explicit when-to-use statement, no mention of prerequisites, and no routing guidance to alternatives.

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

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

With no annotations, the description carries the full burden. It describes the verification behavior and the release condition, but it does not explicitly state whether the operation is read-only or if it has side effects. The trailing 'Record only.' is ambiguous and could be interpreted as a read-only note, but it is not clear. More explicit disclosure of non-mutating behavior would improve transparency.

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 paragraph that front-loads the core purpose and then details checks, output, and the optional record. It is efficient with no filler, though the 'Record only.' phrase adds slight ambiguity. Overall, it is appropriately concise and structured.

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 there is no output schema, the description explains the return format sufficiently (per-field status, documents, disagreements, release flag). It covers the parameters and their interactions. However, the ambiguous 'Record only.' and the lack of explicit error or edge-case behavior leave some gaps. For a tool with this complexity, a bit more detail would enhance 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?

The schema descriptions already cover all parameters at 100% coverage, so the baseline is 3. The description adds context by explaining how readings relate to documents and how records optionally interact, but it does not add significant syntax or format details beyond the schema. The added value is moderate.

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 tool's purpose: to certify a packet of documents against readings. It specifies the exact operation (checking readings, comparing fields across documents), the output (per-field status, documents stating it, disagreements), and the optional record check. This is specific and distinct from sibling tools, which mostly deal with connections, audits, and actions.

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

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

The description provides clear context on what the tool does, including when the optional record parameter is used and the release condition. However, it does not explicitly mention alternatives or exclusions relative to siblings. The guidance is implicit but sufficient for an agent to infer when to use it.

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

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

No annotations exist, so the description carries the full burden — and it discloses the fail-safe policy ('says yes only when it is sure... never guesses'), the human-escalation path, the refusal of unregistered kinds, and the tier limits. It stops short of enumerating the other dispositions (only 'released' is named) or stating auth/rate-limit requirements, so it is rich but not exhaustive.

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?

Front-loaded with the core question and the key non-execution caveat. Dense and mostly waste-free, though the tier/permission fragment ('Free tier: only the demo kinds. Record: any registered kind.') is telegraphic and the release-ticket flow could be tightened.

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

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

With no output schema, the description supplies the return semantics an agent needs (disposition and release_ticket, plus the re-call protocol), covers the nested principal object's effect, and explains error behavior for unregistered kinds. Nothing essential to calling 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?

Schema description coverage is 100%, so the schema already documents kind, args fingerprinting, and the principal/approver-matching rule in detail. The description adds only the flow context around those parameters rather than new per-parameter meaning; baseline 3 applies.

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

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

States a specific operation ('ask whether an action of this kind is authorized') and immediately distinguishes itself from siblings: 'Ogen never performs the action itself — your own system does that.' An agent can tell this gate apart from register_action, report_outcome, or reverse without opening a schema.

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

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

Gives the when (before your system runs an action), the when-not (unregistered kinds are refused; free tier limited to demo kinds), and the follow-up path (call again with the same kind after a human confirms). Explicit lifecycle guidance rather than implied usage.

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

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

With no annotations present, the description carries the full burden and delivers rich detail: repeated 'set' rotates credentials, bound keys pick up new credentials on next read, credentials are never echoed, list output omits credentials, and remove is refused while bound keys exist. This is exemplary disclosure of side effects and security 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 dense, front-loaded with the core purpose, and organized by action, which makes it easy to scan. The trailing fragment 'Record.' is unexplained and slightly undermines an otherwise well-structured 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 multi-action tool with no output schema and no annotations, this covers the critical behavioral context: rotation, read propagation, never echoing credentials, and remove refusal. The main ambiguity is the 'Record.' fragment and only minimal details about what set/remove return, but callers have enough to use 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 coverage is 100%, so the baseline is 3. The description adds meaningful parameter semantics beyond the schema by explaining that calling 'set' with the same name rotates the stored credential and by linking each action to the required parameters (name/kind for set, name for remove).

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: 'Store a credential set once, under a name,' and immediately ties its purpose to bind_source's `source.connection`. The set/list/remove actions further define its scope, making it clearly distinct from sibling tools like bind_source.

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

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

It clearly explains the use case: store credentials once and reference them by name from bind_source. It does not, however, explicitly state when not to use it or compare it with other configuration-oriented siblings like settings, so it lacks explicit 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?

With no annotations, the description carries the behavioral burden and covers it well: the operation is a one-time live read, returns schema information, and 'never the values,' implying a safe introspection behavior. It does not elaborate on error conditions or authentication, but the core read-only profile is 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 compact and front-loaded, opening with the purpose and then the behavioral guarantee. 'Record; free on the demo keys' is terse and somewhat cryptic, which prevents 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 a simple two-parameter introspection tool with no output schema, the description adequately explains the output shape ('field names and types') and the privacy guarantee ('never the values'). It could add failure behavior or a concrete example, but nothing essential for correct invocation 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 schema fully documents 'key' and 'field'. The description adds the live-read and field-names-only context, but it does not add meaningful semantics beyond what the parameter descriptions already state.

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 ('see'), a specific resource ('a bound source'), and the outcome ('field names and types'), while explicitly scoping the tool to discovery rather than values. This distinguishes it from siblings like recall_live_fact or bind_source, which either return values or establish bindings.

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 frames when to use the tool: 'so you can name keys against real fields,' and clarifies that it reads the source 'live' once. It does not explicitly name alternatives or exclusion conditions, so it stops short of a full when/when-not statement.

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

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

No annotations are provided, so the description carries the full burden. It adds some behavioral context with 'Ogen never chooses' and the read-only-sounding 'look at', but it does not explicitly state side effects, permissions, or behavior on invalid action_id. The 'explain' framing sufficiently implies a non-mutating tool, though not exhaustively.

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

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

The description is short and front-loaded with the tool's core value and contents. 'Ogen never chooses' and 'Free and pro' add a bit of behavioral/pricing context but are not verbose; overall it is appropriately sized.

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 tool with no output schema, the description adequately covers what the response will contain by listing the key output categories. It omits response envelope details, error cases, or authorization requirements, but given the low complexity this is a minor gap rather than a critical one.

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

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

Schema coverage is 100% and the only parameter, action_id, is already well-described in the schema as the value returned by commit_gated_action. The tool description adds no additional parameter-level meaning, 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 clearly states the verb and resource ('explain a held action') and enumerates the content delivered: what it waited on, source statements, and a fix template. It does not explicitly contrast with siblings like list_holds or what_it_caught, but the content list makes the tool's specific role evident.

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 person or their assistant to look at' implies when the tool is appropriate, but there is no explicit when-not-to-use guidance or named alternatives. An agent cannot confidently decide between this and list_holds or what_it_caught from the description alone.

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

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

No annotations are provided, so the description carries the full burden. It discloses a retrieval behavior, a maximum result count, and the purpose. However, it is silent on whether the operation has side effects (e.g., does exporting mark or consume fingerprints?), on authentication or secret handling, and on what happens when more than 1,000 records exist. The trailing 'Record.' is cryptic and not explained.

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 well-front-loaded and packs essential behavior, limit, and purpose into one line. However, the second sentence is a single stray word, 'Record.', which adds no value and confuses the reader. This violates the principle that every sentence should earn its place.

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

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

The tool is relatively simple with one optional parameter and no output schema. The description explains what is returned and the use case, but without an output schema more detail about the returned data's structure would help. The incomplete 'Record.' fragment also leaves a loose end, and the description does not explain how the 'secret' is supplied or used.

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 sole parameter 'since' is fully documented in the input schema as an optional ISO timestamp with its filtering semantics. The description does not add any additional meaning to the parameter, 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 states a specific verb ('Return') and a specific resource ('stored read fingerprints'), with a bound ('up to 1,000') and a purpose ('offline verification against your secret'). This makes the tool's function clear, but it does not explicitly differentiate it from sibling tools such as recall_live_fact or audit_log, so the agent must infer the distinction itself.

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

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

The description provides a clear use context: 'for offline verification against your secret' tells the agent when this tool is relevant. However, it does not mention alternatives or exclusion conditions (e.g., 'use recall_live_facts for live queries'), so it stops short of full usage guidance.

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

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

With no annotations, the description carries the behavioral burden and does well by disclosing ordering (newest first), the 100-row cap, and the default exclusion of expired holds. It does not discuss response shape or pagination details, but "List" reasonably implies a read-only operation.

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

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

The description is compact and front-loaded with the primary operation and scope. The only blemish is the trailing "Record.," which is unclear and adds no useful meaning.

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

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

For a simple, all-optional, three-parameter list operation, the description provides the defaults, filtering options, ordering, and row cap needed to invoke it correctly. There is no output schema, so the returned-row shape is not described, but that is a minor gap for a standard list operation.

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 limit, status, and include. The description adds helpful context like "newest first" and "expired unanswered are left out unless you ask for them," but it does not substantially extend the parameter meaning 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 states a specific verb and resource: "List this tenant's held actions," and clearly scopes the operation with status options, ordering, and a row cap. It is immediately distinguishable from sibling tools like explain_hold or commit_gated_action because it is the bulk-listing operation.

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

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

It gives clear context for when to call the tool—listing open, decided, or both held actions for the tenant—and explains the default omission of expired holds. It does not explicitly name alternatives or say when not to use it, so it stops short of a 5.

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

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

Though no annotations are provided, the description is very transparent about behavior: it reads live source, returns specific states, and ensures independent resolution. It discloses that nothing is cached, which is a key behavioral trait. However, it doesn't mention potential errors beyond 'unavailable' or rate limits, but given the detail, it earns a 4. There is no contradiction with annotations since none are present.

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

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

The description is a single, well-structured paragraph that front-loads the core purpose ('Read the live value bound to a key'), followed by behavioral details and usage examples. Every sentence adds meaningful information without redundancy. It's concise yet comprehensive, earning 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?

Given the tool's moderate complexity (two parameters, no output schema, no annotations), the description covers the essential aspects: what it does, return states, parameter usage, and limitations. It doesn't explain the return format in detail (e.g., JSON structure), but since no output schema exists, that might be expected. It could mention error scenarios, but it already covers 'unavailable' and independence, so it's largely complete.

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 provides descriptions for both parameters (key and keys), including examples and maxItems. The description adds value by explaining that one can pass either key or keys, not both, and that duplicates are read once, which goes beyond the schema. Since schema coverage is 100%, the baseline is 3, but the extra clarification on the mutual exclusivity and duplicate handling elevates it to 4.

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 (read live value) and the resource (a key). It explicitly says 'every recall reads the live source at the moment of the question, nothing is cached as truth,' which is a distinctive behavioral trait that differentiates it from siblings like audit_log or what_it_caught. It also clarifies the return states (resolved, ambiguous, unavailable), which aids in correct invocation.

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

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

The description provides clear context on when to use this tool (to read live facts) and how to use it (pass key or keys). It doesn't explicitly state when not to use it or mention alternatives like discover_fields, but the focus on 'live' and 'uncached' gives strong guidance. The mention of 'up to 25' keys and independence of answers is a usage guideline.

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

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

With no annotations, the description carries the behavioral burden and does so meaningfully: it explains that costly actions wait for a person, that a non-'read' cost requires a named approver, and that the approver must be registered first. It also discloses a scope limit ('Each kind with a named approver is one scope; Record covers 5'). It omits re-registration/update semantics and return behavior, but the core mental model is present.

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

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

Four sentences, front-loaded with the core purpose and the key conditional rule about approvers. Little waste, though the final scope sentence ('Record covers 5, and more can be added') is jargon-heavy and less self-explanatory than the rest.

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 mutation tool with no annotations and no output schema, the description covers the essential registration model and the approver prerequisite, with the schema handling parameter detail. However, the cryptic scope/plan sentence leaves the 'Record covers 5' constraint unexplained, and there is no disclosure of what happens on re-registration or what the tool returns.

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 11 parameters in depth, including the cost/approver coupling and omit-to-leave-unchanged semantics. The description reinforces the cost-to-approver rule and the register_approver dependency, but adds no syntax or format 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 opens with a specific verb+resource ('Tell Ogen which fact an action kind depends on, and how costly that action is to undo'), which is clear about what registering an action kind means. It differentiates from the sibling register_approver by making it a prerequisite rather than an alternative. The trailing 'Record only' and scope-counting sentences are cryptic without further context, slightly muddying the purpose.

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

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

It gives one concrete prerequisite ordering: any cost other than 'read' must name an approver, and that person must be registered with register_approver first. However, it never states when to use register_action versus sibling tools like commit_gated_action or bind_source, nor any exclusions. Usage is implied rather than fully guided.

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?

Since no annotations are provided, the description carries the full burden. It reveals that registering an approver affects held actions and that using 'replace' notifies the old address and invalidates passkeys. It also discloses that setting revoke_passkeys has permanent effects. This is strong disclosure of side effects and consequences, going 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?

The description is a bit verbose: 'Tell Ogen where to reach a person by name, so a held action can be sent to them. Record.' could be tightened. The critical side-effect information is embedded in the parameter descriptions rather than the main description, which is fine but not the most front-loaded structure. It's acceptable but not concise.

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

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

For a tool with 4 parameters, full schema coverage, and no output schema, the description adequately explains what happens: the purpose, the side effects of replace and revoke_passkeys, and the relationship to held actions. The main gap is lack of return value info, but since there's no output schema, the description could mention what is returned, but it's not critical for invocation. Overall, a solid definition.

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 describes all parameters. The description adds minimal extra meaning for parameters; it doesn't elaborate on the semantics beyond what the schema says. However, the description reinforces the critical behavior of 'replace' and 'revoke_passkeys' consistently. 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 the verb 'register' and the resource 'approver,' and clarifies its purpose: to tell Ogen where to reach a person so a held action can be sent. However, it is somewhat verbose and could be more direct about the core action. It does not explicitly differentiate from sibling tools like register_action or set_contact, though the name itself helps.

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 this tool (when you need to record where to reach an approver) but does not explicitly state when not to use it or mention alternatives. The brief 'Record.' at the end is not helpful. Without explicit exclusions or alternative routing, an agent may struggle to choose between this and register_action or set_contact.

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?

There are no annotations, so the description carries the behavioral burden. It discloses the two key behavioral traits: Ogen only records the report and never runs the action, and only one report per ticket is allowed. It does not describe duplicate handling or what response the caller receives, but the safety-relevant behavior is clearly exposed.

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

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

The description is front-loaded with the core purpose, followed by the one-per-ticket constraint and the key behavioral distinction. The final fragment 'Record.' is redundant filler, but the overall length is appropriate and no essential information is buried.

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

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

Given the moderate complexity, full parameter schema coverage, and no output schema, the description is largely complete: it explains what is being reported, the ticket requirement, the one-report-per-ticket limit, and that the tool does not execute anything. It could be slightly stronger by naming the preceding confirmation step or expected acknowledgement, but it 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 coverage is 100%, so the baseline is 3. The description mostly restates the ticket provenance and the outcome concept already present in the schema, without adding format, relation, or conditional details. The schema remains the primary source for 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?

The description states a specific verb ('report'), a specific resource ('a confirmed action's outcome'), and the identifying metadata ('with the release_ticket its confirmation issued'). It also distinguishes itself from execution tools by explicitly saying 'it never runs the action', so an agent can separate it from siblings like commit_gated_action or reverse_action.

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

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

It gives a clear context: after a confirmed action, tell Ogen whether the action ran, with one report per ticket. It also clarifies that this tool records rather than executes, but it does not explicitly name alternative tools or provide a when-not-to-use list, so it falls short of full explicit guidance.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior. It states that 'reverse' only marks an action and does not alter anything else about the account, and it clarifies the effect of 'restore'. It also mentions that a named person is required. However, it does not reveal potential side effects, reversibility, permission needs, or what happens if the action is already reversed, nor does it clarify the ambiguous 'Record.' instruction. It provides some transparency but lacks thorough behavioral disclosure.

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 concise—two sentences plus 'Record.'—and clearly separates the two action modes with labels. The main points are front-loaded, making it easy to scan. The trailing 'Record.' is cryptic and potentially unnecessary, but it does not overly detract from the overall clarity. It is well-structured and free of redundant wording, earning a 4.

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 six parameters with conditional requirements, and the description explains the two modes but does not explicitly mention which IDs are needed for each (relying on the schema). It does not describe return values or post-action effects, and there is no output schema. Given the schema covers parameters thoroughly, the description is adequate for basic usage but lacks completeness regarding implicit behavior and outcomes after the call.

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

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

The input schema has 100% coverage for all six parameters, each already described with clear conditions (e.g., action_id required for 'reverse', rule_id for 'restore'). The description adds no new parameter meaning beyond what the schema provides. It does summarize the 'named person' requirement, but that is already encoded in the schema. Since schema coverage is complete, a 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 clearly defines two distinct behaviors: 'reverse' marks an action as reversed to prevent repetition, and 'restore' puts a set-aside correction back into force. It uses specific verbs ('mark', 'put') and resources ('action', 'correction'), and emphasizes that nothing else changes. This precisely explains what the tool does and effectively distinguishes between its two modes, making it immediately clear to an agent.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention any sibling tools, nor does it state conditions like 'use this when you need to undo an action' or 'if you want to reverse a different entity, use another tool'. The only explicit requirement—'Named person required either way'—is a precondition, not a usage guideline. There is no exclusion or comparison to other options, leaving the agent to infer usage context.

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

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

No annotations are provided, so the description carries the full burden. It discloses important behaviors: 'stored encrypted, never returned', 'shown once', the exact confirm phrase needed to switch to observe, that deleting/off ensures key clearing, and the caller's hard limits. That is strong transparency. It could go further on whether observations/evidence are retained, what a 'door' page exposes publicly, and whether disabling assist 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 one long dense block. It front-loads the overall purpose and then enumerates actions, which is good structure, but the sentences are very long and packed with clauses. There is little visual separation between action behaviors, making it harder to scan than necessary. The final 'Record.' is terse and slightly confusing. It's appropriately sized for the complexity, but the structure could be improved with clearer segmentation.

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 16 parameters, 8 actions, no output schema, and no annotations, the description does a thorough job covering what each action does and key constraints. It leaves some gaps: what the caller_list output looks like, what the door page exposes, and whether mode/contact changes are reversible. But for a complex multi-action tool, this is close to complete for an agent to pick the right action and parameters.

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 action-specific semantics for several parameters that the schema alone doesn't emphasize: the exact confirm string for observe, the acknowledge+confirm pairing, the one-time key display, the constraint that allowed_kinds must be registered via register_action, and that a fresh label mints a key. Some parameters (model default, daily_cap default 50, weekend enum) are only in the schema, so it doesn't fully compensate, but it adds clear value.

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

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

States a specific verb and resource ('Change one of this tenant's standing settings'), and enumerates the eight action values, each with a clear functional description (mode, contact, evidence, assist, caller_set, caller_remove, caller_list, door). It's a polymorphic settings tool with multiple sub-resources, so 5 would require clearer top-level framing that 'action' selects one of eight distinct settings. Still, the purpose is unambiguous.

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?

For each action, the description explains the when/why: gate vs observe tradeoff, switching conditions, and what 'observe' watches. It also names constraints on callers (what a caller may only call). This goes well beyond siblings, routing the agent to the correct action and the correct constraints. The only gap is no explicit references to sibling tools like register_action or commit_gated_action by name for cross-tool flow, though commit_gated_action and explain_hold are mentioned.

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

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

No annotations are provided, so the description carries full responsibility for disclosing behavioral traits. It indicates the action is a write (recording) and that it prevents future repeat questions, but it does not describe side effects, such as whether an existing fix for the same key is overwritten, whether the fix is immediately active, or any authorization/error conditions. The description is too sparse for a mutation tool.

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

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

The description is short and front-loaded with purpose, but it includes a redundant final 'Record.' that adds no information. Removing that tail would make it tight. The structure is acceptable but not optimal due to the unnecessary word.

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 4 required parameters, no output schema, and no annotations, the description does not sufficiently cover operational context. It states the purpose and names a prerequisite, but omits behavior on duplicates, idempotency, or success/error outcomes. An agent calling this tool would need external knowledge about persistence and edge cases, which is a notable gap for a mutating 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?

The input schema has 100% description coverage, so the schema already fully documents each parameter. The description adds only 'Named person required,' which merely reinforces the schema's existing note that taught_by is 'The named person recording this fix.' With full schema coverage, the baseline of 3 applies; extra meaning is not provided.

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 ('Record a person's correction') and the intended outcome ('so nobody is asked the same thing twice'), which clearly identifies the tool's purpose. It does not explicitly name or contrast sibling tools like restore_fix or what_it_caught, so it doesn't fully maximize distinguishability, but the core purpose is unambiguous.

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 a usage context (when a person provides a correction that should be persisted for future reference) and states a prerequisite ('Named person required'). However, it does not explicitly say when to use this tool instead of alternatives such as restore_fix or recall_live_facts, nor does it mention any exclusions. This is adequate but not 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?

With no annotations present, the description carries the behavioral disclosure burden. It discloses that webhooks are HTTP POSTs, signed for verification, scoped to one URL per tenant, and that remove stops them. It does not mention permission requirements or response handling, but for a configuration tool these are the key behaviors and are covered.

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 concise and front-loaded with the primary action 'set' and its behavior. However, the trailing 'Record.' is an unclear fragment that seems to add no value and could confuse an agent. The overall structure is otherwise efficient, but this stray word costs clarity.

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?

While the schema covers parameters well, the description omits an explicit statement that 'set' requires a URL, which the schema implies but does not enforce (only action is required). The mystery 'Record.' suggests incomplete editing, and there is no information about the response or result of the operations. For a tool with no output schema, the description should clarify these gaps.

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

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

The schema provides 100% description coverage for url, action, and secret, so the baseline is 3. The description adds the 'one URL per tenant' constraint and the signing detail, which are useful global context, but it does not add much parameter-specific meaning beyond the schema. The conditional requirement of url for set is mentioned in the schema, and the description doesn't reinforce 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 clearly communicates a webhook configuration tool with two actions: set and remove. It specifies the event trigger (held/escalated actions) and the signing behavior, making the tool's purpose evident. It doesn't explicitly contrast with siblings, but none of the listed tools serve a similar webhook function, so differentiation is not needed.

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 usage context by explaining when webhooks fire (when an action is held or escalated), which tells an agent when to set one up. However, it offers no explicit guidance on when to choose this tool over alternatives, nor any exclusions or prerequisites. The instruction to use set vs. remove is clear, but broader decision 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?

With no annotations, the description carries the burden of behavioral disclosure. It proactively clarifies that the tool is not scheduled and that all numbers come from calls already made, preventing the agent from assuming it triggers work. It does not mention permissions or explicit read-only status, but for a report tool these are lesser gaps.

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

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

The description is short, front-loaded with the main purpose, and uses a clear colon list of report contents. The 'Free and pro' note adds little to tool invocation, but it is minor and does not make the description bloated.

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 report tool, the description is reasonably complete: it explains what the report contains and that it is not timer-based. The default window is left to the schema, and no output schema exists, but the core behavior is well covered.

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

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

The schema already documents the sole parameter 'days' with its range, default, and meaning, so schema description coverage is 100%. The description's 'over a window' only loosely refers to the parameter and adds no new semantic detail, 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 clearly defines the tool as a short report of Ogen's activity over a window, listing the four report categories. It is specific about what the tool returns, but it does not use a verb and does not explicitly differentiate it from siblings like audit_log or recall_live_fact.

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: this is a retrospective report, and it explicitly states 'nothing here runs on a timer — every number comes from calls already made.' This tells an agent when to use it, but it does not name alternatives or provide exclusion conditions, 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.