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

The annotation idempotentHint=false directly contradicts the description's claim that 'key: an idempotent retry.' This is a serious inconsistency that could mislead an agent about retry safety. The description also does not clarify permissions, review effects, or what happens to existing 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?

It is short and front-loads the action, but the semicolon-separated fragments are cryptic rather than efficient. Some details earn their place, yet the lack of structure makes it harder to parse than a well-formed sentence.

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 10-parameter write tool with no output schema, the description is far from complete. It omits most parameter semantics, does not explain the write/review lifecycle beyond status='proposed,' and contains an idempotency contradiction that undermines trust in the 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 description coverage is 0% across 10 parameters, so the description must compensate, but it explains only value, scope, key, and status. Critical parameters like subject, predicate, evidence, by, task, and detail are left undocumented, and required subject/predicate receive no semantic explanation.

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 says 'Record what you learned,' which gives a verb but an ambiguous resource; it does not clarify that this stores an annotation/knowledge claim, nor does it distinguish the tool from siblings like context, history, search, or related. The parenthetical '(value: any JSON)' hints at structured storage but leaves the core purpose vague.

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 some conditional usage rules: tenant/global scopes require evidence, key enables idempotent retries, and status 'proposed' awaits review. However, it never states when to use annotate versus alternatives such as context or history, nor does it clearly mark when not 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?

readOnlyHint already tells the agent this is a safe read, so the bar is lower; the description still adds real behavior — depth=1 pulls in neighbours (a cost/scope signal), detail levels run up to 'full (audit)', and as_known_at yields a historical view. However, nothing is said about result size, truncation, or how only/exclude narrow output, which is exactly the kind of behavioral detail this tool needs.

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 question is front-loaded in the first clause, and the remainder is a compact parameter gloss with no filler. It is so compressed that a few fragments ('task: its memory') become hard to parse, which slightly undercuts the terseness.

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 8-parameter tool with no output schema, the description covers the query and most filtering semantics but omits any statement of return shape and says nothing about two of the parameters. An agent could call it, but would be guessing about output size and the meaning of `only`/`exclude`.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does for most of it: subject format ('<kind>:<id>' or a list), as_of, as_known_at, depth semantics, and the detail enum with its default. It leaves `only`, `exclude`, and `task` opaque ('its memory' is cryptic), so it compensates well but not completely for the 8 undescribed parameters.

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

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

The description states a specific question the tool answers — 'What is true about a subject now or at as_of' — and enumerates the payload (facts with `since`, relations, rule evaluations), which pins down the resource better than the bare name 'context' does. It implies a current-state/temporal-query role that distinguishes it from a logged `history`, though it never explicitly names its 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?

It gestures at when the tool applies ('now or at as_of', 'as Keel knew it then'), but there is no explicit guidance on choosing it over `history`, `search`, `related`, or `annotate`. The rest of the text is parameter gloss rather than usage policy, and no when-not conditions are given.

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?

readOnlyHint=true already covers safety, and the description adds genuine behavioral context beyond it: default result ordering (oldest first), that limit retains the *latest* entries and that limit=0 returns everything, and the null-vs-absent semantics of the replaced value. What is missing is any note on pagination or the result shape, which would matter given no output schema.

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

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

The text is short and every clause carries information, but it is a semicolon-chained run-on with no lead verb and heavy domain jargon ('Keel', 'watermark', 'tenant then'), so it is not front-loaded and requires re-reading. Density here buys brevity at the cost of parseability.

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 10-parameter, zero-coverage, no-output-schema tool, the description covers most of the tricky temporal semantics, which is more than most. It still leaves two parameters (task, scope) undocumented and misstates the detail enum, and it never says what a returned record looks like, which the agent needs since no output schema exists.

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

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

Schema coverage is 0%, so the description must carry all ten parameters, and it explains subject, since, until, predicate, as_known_at, changed_since, limit and detail. It leaves 'task' and 'scope' (agent/task/tenant/global) entirely unexplained, and its 'detail: concise or full' contradicts the three-value enum that also allows 'text'; 'was' is described but is not actually an input parameter, which is confusing.

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 opening clause 'Facts over time of a subject, oldest first' describes the resource and the ordering, but never supplies a verb – the agent must infer that this is a read/query operation. It partially differentiates scope ('no subject + since/until: every change in the tenant') but none of the sibling tools (context, search, related) are named or contrasted.

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

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

There is conditional guidance for one branch – omitting subject while supplying since/until yields a tenant-wide change feed. However there is no explicit when-to-use-this vs. search/context, no statement of prerequisites or cost, and the relationship between as_known_at and changed_since is only hinted at, leaving the agent to infer which one applies.

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 readOnlyHint=true, the description discloses meaningful behavior: time-travel via as_of, multi-hop traversal via depth, limit semantics including 0 meaning unlimited, and the truncated-result marker `{"more": ...}`. That truncation signal is genuinely useful context an agent cannot get from annotations or 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?

Extremely compact and front-loaded with no filler, but the telegraphic semicolon style edges into ambiguity — "depth 2-3 walks further" could be read as a permitted range rather than a recommendation, and `{"more": ...}` uses placeholder syntax without explanation.

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

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

No output schema exists, so the description should describe the return shape; it only hints at it through the truncation marker. With readOnlyHint covering safety and a 5-param schema fully undocumented, an agent still lacks the result structure and the as_of format needed for confident first-call use.

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

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

Schema description coverage is 0%, so the description carries the burden, and it does touch all five parameters (subject, relation, as_of, depth, limit). However it gives no format for `as_of` (ISO? relative?), no explanation of what happens beyond depth 3, and no default values, so it only partially compensates.

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 phrase "Neighbours of a subject by relation" names the resource and the traversal operation, but there is no leading verb (list/get/query) and no reference to siblings like search or context. An agent can infer it is a graph-neighbour query, but distinguishing it from `context` or `search` requires inference.

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

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

No sentence says when to use this tool instead of `context`, `history`, or `search`. The only usage-ish hints are parameter behaviors ("depth 2-3 walks further", "limit (0: all)"), which guide invocation but not tool 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?

Beyond the readOnly annotation, the description discloses cost-relevant behavior: key/count cost least, full is a costly audit, and paginated results may come as a cut list beginning with {"more": ...}. It also explains temporal semantics via as_of/as_known_at, though it remains terse.

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 and densely packed, but its telegraphic semicolon-heavy style makes it harder to parse than necessary. It is reasonably sized for a 16-parameter tool but sacrifices clarity for brevity.

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 16-parameter search tool with no schema descriptions and no output schema, the description is incomplete: it does not explain mode, depth, exclude, per_kind, or min_score, and gives only fragmentary hints about return values. An agent would need to infer too much to invoke it reliably.

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

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

Schema description coverage is 0% across 16 parameters, so the description must carry parameter meaning. It explains several important params (kind, rule, text, where, related_to, via, as_of, as_known_at, detail, limit/after), but omits mode, depth, exclude, per_kind, and min_score, leaving substantial gaps.

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 "Find subjects", which gives a verb and resource, and then lists filtering modes like kind, rule, text, and where. However, "subjects" is undefined and the description does not clearly distinguish this tool from siblings such as context, history, or related.

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 guidance is implied through phrases like "brief adds facts (no context call needed)" and "full: an audit, costly", which help choose a detail level. But there is no explicit statement of when to use this tool instead of context, history, annotate, or related.

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