Komplyt Zero

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely non-obvious behavior on top: models are computed nightly on the hosted service, not on request, so reads can be stale. It also discloses the two return signals an agent must handle — status "not_computed" for an uncomputed scope and "computed_at" for freshness — which prevents misinterpreting an empty/deferred result.

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, both earning their place: the first establishes what is read and how lens changes the output, the second front-loads the critical constraint (precomputed, possibly absent). No filler or restatement of the title.

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

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

With no output schema, the description does the right work by naming the status and freshness fields and by distinguishing the three lens result types. It stops short of describing the shape of a model payload per lens, but for a read-only tool with full schema coverage this is close to sufficient.

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 enums are documented, so the schema already carries the mechanics; the description adds meaning by mapping each lens to what it actually returns (methodology patterns, resiliency metrics, process flows). It does not clarify what id is required for, but the schema handles that.

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 ("Read the stored meta-model") and enumerates the three scopes and three lenses, so the resource is unambiguous. It does not differentiate itself from the sibling kg_query, which an agent might reasonably reach for instead.

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 through the scope/lens enumeration and warns that models are precomputed rather than on-request, which effectively tells the agent not to expect a fresh recompute. However it never states when to prefer this over kg_query or kg_status, nor any prerequisites for the id field per scope.

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

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

Annotations already declare non-read-only, non-idempotent, non-destructive behavior, and the description adds meaningful context beyond that: the active-session requirement, that new nodes start fully active, and that an embedding is generated for semantic search. It stops short of describing the response or how relates_to failures are handled.

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

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

Three tight sentences with no filler, and the core purpose plus the session prerequisite are front-loaded. Slightly list-like but every clause carries information.

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

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

No output schema exists, so ideally the description would hint at what is returned (e.g. the new node ID). It compensates well by covering prerequisites, default activation state, embedding generation, and linking, which is nearly 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 coverage is 100%, so enum values for type/status, defaults for project/container, and the max-20 limit on relates_to are already documented. The description only restates the linking capability and embedding behavior, which adds marginal value over 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?

States a specific verb+resource ('Create a knowledge node') and enumerates the node kinds, plus the side effects of embedding generation and relate_to linking. It is clear what the tool does, though it does not explicitly contrast itself with kg_node_update or kg_relate.

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 an important precondition ('Requires an active session'), which implies the tool is used mid-session. However, it never says when to create a new node versus updating an existing one via kg_node_update, or when linking should be handled by kg_relate 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?

Goes well past the destructiveHint annotation: it discloses that tags replace the entire list, that content overwrites prior content and regenerates the embedding, that a failed embedding aborts the update leaving the node unchanged, and that session auth is required. This is exactly the mutation-risk context an agent 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?

Three sentences, front-loaded with what can be updated, followed by the two highest-risk semantics and the auth prerequisite. No padding or repetition of the tool name.

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?

Covers atomicity on embedding failure, wholesale tag replacement, reactivation, and session requirement for a destructive mutation with no output schema. The only gap is whether the updated node is returned, which is minor for a tool of this complexity.

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

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

Schema coverage is 100% and the schema already documents full-list tag replacement, empty-array removal, omit-to-keep, and embedding regeneration. The description largely restates those facts, so it adds little beyond what structured fields already provide; 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 verb (update) plus the resource (an existing knowledge node) and enumerates the mutable fields (status, content, tags) and the side effect of reactivation. The word 'existing' implicitly separates it from the sibling kg_node_create, but no sibling is named, so differentiation is inferred rather than stated.

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

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

'Requires an active session' is an explicit prerequisite, and the tag/content sentences describe when each field's side effects apply (full-list replacement, overwrite). It never names an alternative tool or a when-not-to-use case, so usage is clear but incomplete on routing.

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 critical disclosure is that this is not a pure read: with an active session, returned nodes are reactivated and their decay score boosted, while node content is unchanged. That explains why annotations carry readOnlyHint=false with idempotentHint=false, which the description reinforces rather than contradicts. It stops short of stating the exact write fields (last_activated, session_activated), which only the schema covers.

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

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

Three tightly packed sentences that front-load the search purpose, then escalation guidance, then the side-effect warning. Every sentence earns its place; only the parenthetical could be trimmed slightly.

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 tool with no output schema, the description covers the query modes, ranking, spreading activation, and the non-obvious write side effect. Minor gaps remain around the edge/neighbor inclusion flags and the limit, but those are fully specified in the schema, so an agent has what it needs to call 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 every parameter is already documented, including the read_only string-coercion caveat and enum values. The description adds conceptual meaning for spread and read_only but says nothing about the other 14 parameters, so it only marginally exceeds the schema 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?

States a specific verb and resource ('Search knowledge'), names the retrieval modes (semantic similarity, type, status, recency) and the return ('nodes ranked by relevance'). This is unambiguously the read/query tool among siblings like kg_node_create, kg_node_update, and kg_relate.

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 concrete conditional guidance: 'Use spread=true to find related nodes via spreading activation' and 'pass read_only=true to search without changing anything.' It lacks explicit when-not-to-use direction versus siblings (e.g., kg_meta_model), but the situational guidance for the two tricky flags 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?

Annotations only flag non-read-only, non-idempotent, non-destructive; the description adds real behavior: existing edges gain weight rather than duplicating, both endpoint nodes get their decay scores boosted, and a session must be active with a 100-edge cap. These are side effects and limits the agent could not infer from structured fields, and the reinforcing-weight behavior is consistent with idempotentHint=false.

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

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

Three short sentences, front-loaded with the action and its upsert semantics, then side effects, then constraints. Nothing redundant and nothing padding.

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 mutation tool, the description covers side effects, session requirement, and quota, which is most of what an agent needs. With no output schema, it leaves the return value (what the created/reinforced edge looks like) unspecified, a minor but real gap.

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

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

Schema coverage is 100% and both parameters are documented in the schema, including the 'node:abc123' ID format example. The description only implies directionality ('between two knowledge nodes') without adding format or ordering semantics beyond what the schema already provides, 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?

States a specific verb and resource ('Create a relationship between two knowledge nodes') plus the upsert variant ('reinforce it if it already exists'). The edge-between-nodes framing cleanly separates it from sibling node tools like kg_node_create and kg_node_update without needing to name 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?

Gives a hard precondition ('Requires an active session') and a quota ('limited to 100 edges per session'), which directly shape when the call can be made. It does not name alternatives (e.g., kg_node_create for the nodes themselves) or state when not to use it, so it stops short of full routing guidance.

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

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

Annotations already declare non-destructive, non-read-only, non-idempotent. The description adds genuinely useful context beyond them: persisted data survives the end, and subsequent writes are blocked until a new session starts. Missing: behavior when no session is active or whether repeated calls error.

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

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

Two short sentences, action first, consequence second. No filler and nothing important 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?

For a zero-param lifecycle tool with annotations covering safety hints and no output schema, this is nearly complete: it tells the agent what survives and what becomes unavailable. Only edge-case behavior (calling without an active session, idempotency of repeated ends) is unstated.

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?

Zero parameters, so the baseline is 4; there is no parameter semantics to explain, and the description correctly avoids inventing any.

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

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

States a specific verb+resource ('End the current session') and clarifies consequences (nodes/edges kept). It does not name the sibling kg_session_start as the counterpart, but the start/end pairing makes the distinction obvious.

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?

Implies the right moment (when finished writing) and states the prerequisite for continuing work: a new session must be started before further writes. It lacks an explicit 'when not to use' or a named alternative, 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so 'Read-only' in the description is mostly repetition. What the description does add is the scope of what is retrieved (session metadata plus node counts by type), which helps an agent anticipate the read's breadth, though return format and aggregation detail remain unstated.

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

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

Two short sentences, with the resource and returned fields front-loaded. The trailing 'Read-only' duplicates the annotations and is the one non-earning fragment.

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 carries the burden of describing returns and does so at a high level (session fields and node counts by type), enough for an agent to decide to call it. It could note behavior when no session is active, which keeps it from a 5.

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

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

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate beyond confirming it operates on the implicit current session.

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 and resource ('Get details of the current session') and enumerates the returned fields (number, start time, project, notes) plus node counts by type. It does not explicitly contrast with siblings like kg_status or kg_meta_model, so it falls short of a 5.

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

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

'current session' implies the context in which it applies, but the description never states when to use it instead of kg_status or kg_meta_model, nor any prerequisites such as an active session. Usage is only inferable.

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

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

Discloses side effects not captured by annotations: decay applied to usage-based scores of existing nodes (while content is unchanged) and optional creation of the project plus default workspace records on first use. This is exactly the mutation context the false destructiveHint cannot convey.

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

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

Two tight sentences, front-loaded with the primary action and precondition, then side effects. No wasted text.

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?

Covers preconditions, side effects, and project creation for a 3-param tool with annotations. Minor gap: with no output schema, it doesn't indicate what a started session returns (e.g., a session handle), which would help the agent use 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?

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema for create_project — explaining it creates the project and default workspace records on first use. Notes and project params rely 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?

States a specific verb ('Start') and resource ('working-memory session'), plus the key precondition that it's required before creating nodes or edges. Distinct from siblings like kg_session_end and kg_session_info.

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?

'Required before creating nodes or edges' gives clear when-to-use context. It doesn't explicitly name alternatives like kg_session_end, but the precondition makes the selection obvious.

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, so 'Read-only' is largely redundant. The description does add real value beyond annotations by disclosing the shape of the payload (todos, problems, recent decisions, node count, session info), which is not derivable from any structured field.

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 payload contents are front-loaded in the first sentence, which is the right ordering. The standalone 'Read-only.' sentence restates an annotation and is the one piece of avoidable text.

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

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

With one optional parameter, rich annotations, and no output schema, the description does the heavy lifting by describing what the status snapshot contains. The remaining gap is the lack of any note on how it relates to kg_session_info, whose scope it partially overlaps.

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 single project parameter is already documented as 'Only count and list nodes in this project'. The description adds only that the filter is optional, matching the schema's non-required status — correct but minimal, 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?

Names a specific verb (get) and resource (working memory status), then enumerates exactly what the overview contains: todos, problems, decisions, approaches, node count, session info. It does not distinguish itself from the overlapping kg_session_info sibling, which also returns session information, so an agent must infer the boundary.

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

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

'Optionally filter by project' is the only usage guidance given; there is no statement of when to prefer this over kg_query or kg_session_info. The intent (a dashboard-style snapshot) is implied by the enumerated contents but never stated as a when-to-use rule.

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