A search engine that learns from feedback, over embeddings: one tool per API route.
Scored across 12 tools
The edge-scoring trio is genuinely ambiguous: create_edge is really a search-and-store operation (misleadingly named), while put_edge and update_edge both write scores and differ only in whether the edge already existed. The descriptions explain the distinction, but an agent can easily misselect among these three.
Every tool follows a clean verb_noun pattern (create_node, get_edge, list_nodes, update_edge, delete_node, etc.) with no mixing of conventions or vague verbs. The set is fully predictable from names alone.
Twelve tools is well-scoped for a node/edge ranking grid, with CRUD split cleanly across the two resources and a grid accessor. Each tool earns its place with no filler.
Node CRUD (create/get/list/update/delete) and the full edge lifecycle including scoring are covered, plus a search flow via create_edge. Only minor gaps remain, such as no grid create/update/delete or bulk operations.
POST /nodes/{nid}/edges, the search: from query node nid, the best node it has not been shown yet,
among those whose key starts with prefix ("" for any), stored as a new edge: id is the found node's id,
score is null until you score it (update_edge). Null when nothing is left. Call again for the next.
| Name | Required | Description | Default |
|---|---|---|---|
| nid | Yes | ||
| prefix | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose meaningful behavior: the returned edge's `id` is the found node's id, `score` is null until update_edge is used, and the call returns null when exhausted. It does not cover permissions, error cases, or side effects on the graph beyond the new edge, but the lifecycle contract is unusually well spelled out.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One dense sentence plus one short one, front-loaded with the endpoint and no filler. The colon/semicolon chaining is information-rich rather than padded, though it reads as a run-on and could be split for scanability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value documentation is not strictly required, yet the description still explains the returned fields' meaning and the exhaustion case. For a 2-parameter tool with an odd search-side effect this is nearly sufficient; only idempotency/duplicate-edge behavior is unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: `nid` is identified as the query node and `prefix` as the key filter with its default-when-empty behavior ('"" for any'). Both parameters gain semantics the schema lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb+resource (a new edge is created) and explains the unusual search semantics: it picks the best not-yet-shown node reachable from `nid` whose key starts with `prefix`. It even names update_edge as the follow-up. It stops short of contrasting with put_edge, so an agent must infer why two edge-creation tools exist.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells the agent to iterate ('Call again for the next') and states the terminal condition ('Null when nothing is left'), plus routes scoring to update_edge. There is no guidance on when to prefer this over put_edge/create_node, so it is clear context without full alternative disambiguation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
POST /nodes: add a node. An item gets a key, a path unique in the grid (e.g. "/items/42"), so searches
can find it; a query gets none. emb is its embedding, 1 to 2048 floats from any model; use one model per
grid. Returns its id and key (not its emb, to keep replies short; get_node has it).
| Name | Required | Description | Default |
|---|---|---|---|
| emb | Yes | ||
| key | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden well: it discloses that items need a grid-unique key while queries do not, that embeddings must be 1-2048 floats from a single model per grid, and that the response deliberately omits emb. It does not cover permissions, error behavior, or write irreversibility, which keeps it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the endpoint and core action, then packed with dense parenthetical constraints. Every clause is informative, though the run-on second half is dense enough to slow scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values would not strictly be needed, yet the description still clarifies the reply (id and key, not emb). Combined with the key/query semantics and embedding rules, an agent has enough to call it correctly; only failure modes and grid-permission context are absent.
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 compensate, and it does: key is explained as an item-vs-query discriminator with uniqueness and example format, and emb is explained with its float range and the one-model-per-grid constraint. Both parameters gain meaning not present in the bare 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?
Opens with a concrete verb+resource ('add a node') and immediately distinguishes the two node kinds (item vs query) that this endpoint creates. An agent can tell it apart from update_node, delete_node, and get_node without opening any 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?
Usage is implied rather than stated: the notes about when an item gets a key and when a query does not make the intended contexts inferable. There is a routing hint toward get_node for embeddings, but no explicit when-to-use/when-not guidance relative to siblings like update_node or create_edge.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
DELETE /nodes/{nid}/edges/{eid}: forget a result, so it can be suggested again; its score no longer trains.
| Name | Required | Description | Default |
|---|---|---|---|
| eid | Yes | ||
| nid | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that this is a soft "forget" rather than a hard purge (the result can be suggested again) and that it has a training side effect ("its score no longer trains"). It still omits permission requirements and whether the effect is immediate/undoable, so not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence: the endpoint, the action, and the two consequences of the action. Every clause earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need no explanation, and the description supplies the key mutation semantics that annotations would otherwise cover. The remaining gap is parameter-level detail for nid/eid, which matters given 0% schema coverage.
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% and neither nid nor eid is documented in the schema. The path template "/nodes/{nid}/edges/{eid}" does clarify that nid identifies the node and eid the edge, which is real added meaning, but it gives no format, type, or provenance guidance for the two undocumented 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?
States a specific verb (DELETE/forget) on a specific resource (edge) and immediately explains what an edge deletion means semantically: the result can be suggested again and stops training. That is far more than a tautology. It does not explicitly contrast itself with update_edge or put_edge, 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?
"forget a result, so it can be suggested again" implies the usage context (undoing a previously accepted/suggested edge rather than removing a node or editing an edge), but there is no explicit when-to-use/when-not statement and no named alternative among the many edge siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
DELETE /nodes/{nid}: delete a node and every edge from or to it; its scores no longer train.
| Name | Required | Description | Default |
|---|---|---|---|
| nid | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose two important traits: the cascading deletion of all connected edges and the downstream effect that 'its scores no longer train'. It omits irreversibility, permission requirements, and whether this is a hard or soft delete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that leads with the operation and follows with the consequential cascade and training effects. Slightly redundant REST path notation, but no wasted clauses.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity one-parameter tool with an output schema already present, the description covers the essentials, especially the destructive cascade and training impact. Missing only irreversibility and authorization context that an unannotated mutation tool would ideally state.
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% for the single parameter, so the description must compensate. It references {nid} as the path identifier, clarifying that it targets one node, but gives no format or source details for the ID beyond 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 ('delete a node') and adds the cascade scope ('every edge from or to it'), which meaningfully separates it from delete_edge. It never names a sibling explicitly, but the action and resource are 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?
Usage is only implied by the tool name and REST path; there is no explicit when-to-use, when-not-to-use, or pointer to an alternative such as update_node for non-destructive edits. An agent can infer intent but gets no routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GET /nodes/{nid}/edges/{eid}: one result of query nid, and its score (null if not scored).
| Name | Required | Description | Default |
|---|---|---|---|
| eid | Yes | ||
| nid | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It notes the score can be null when unscored, which is useful, but it says nothing about read-only safety, permissions, error behavior for missing nid/eid, or any other trait beyond the return value already covered by the 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?
A single short sentence that front-loads the endpoint and follows with the return nuance. Efficient, though the 'one result of query' clause is more confusing than informative.
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 output schema exists, so return values needn't be re-explained, and the core fetch purpose is conveyed. However, with 0% parameter documentation and no annotations, the definition leaves the agent guessing about parameter meaning and behavioral traits.
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% and neither parameter has a description, so the description must compensate. It only echoes the {nid} and {eid} path placeholders without explaining what a node id or edge id is, their format, or whether eid is scoped to nid.
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 concrete verb (GET) and a specific resource path (/nodes/{nid}/edges/{eid}), so the agent can tell it fetches a single edge. The phrase 'one result of query `nid`' is vague and it never distinguishes itself from siblings like list_edges or get_node, but the endpoint makes the purpose clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to use this tool versus list_edges, get_node, or the other edge tools. The single-edge fetch is only inferable from the URL template, not from any explicit guidance or exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GET /: the grid the API key opens, by name.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. 'GET /' weakly implies a read, and 'the API key opens' hints that auth is derived from the API key, which is mildly useful. But it says nothing about permissions, error behavior, or what happens if the key maps to multiple/zero grids. An output schema exists, so return format need not be 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?
A single short fragment with zero padding; nothing redundant. It is perhaps over-terse rather than over-long, but it is appropriately sized and front-loads the operation.
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 structurally simple (0 params) and the output schema covers the return shape, so much of the burden is lifted. Still, with no annotations and a confusing 'by name' clause, the definition is only minimally sufficient for an unauthenticated reader to understand what this root-level call 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?
The tool takes zero parameters, so per the baseline rule a 4 applies and there is nothing for the description to clarify. The only caveat is that 'by name' implies a naming selector that no parameter provides, which adds mild confusion rather than 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?
It does name a verb (GET) and a resource (the grid), and 'get_grid' is the only grid-scoped tool among node/edge siblings, so differentiation is implicit. But the phrasing 'the grid the API key opens, by name' is cryptic and self-contradictory against a zero-parameter schema, leaving the exact semantics of the resource partially unclear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, no prerequisites, and no mention of alternatives or when this is preferable to the node/edge tools. The agent gets no routing signal beyond the name itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GET /nodes/{nid}: a node, with its key (null if it has none) and its embedding emb.
| Name | Required | Description | Default |
|---|---|---|---|
| nid | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does disclose a useful non-obvious trait — the returned key may be null — but says nothing about auth requirements, error behavior for an unknown nid, or whether the embedding is always 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?
One compact sentence, front-loaded with the operation and immediately following with the return shape. Nothing redundant, though the phrasing is terse enough to border on under-specification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-entity read with an output schema already documenting the return structure, the description is close to sufficient. Missing only failure-mode and auth context, which is minor given the tool's simplicity and the presence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the single parameter 'nid' is bare. The path template '{nid}' implicitly conveys that the argument is the node identifier, but no format or constraints are given, so the description adds only minimal 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?
States a specific verb+resource ('GET /nodes/{nid}') and clarifies it returns a single node, which distinguishes it from list_nodes/get_grid. It does not explicitly name a sibling, but the path template makes the single-entity scope 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?
Usage is only implied: fetching one node by id versus listing nodes or fetching edges/grids. There is no explicit when-to-use statement, no mention of what to do if the node is absent, and no named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GET /nodes/{nid}/edges: a query's results so far, each an edge with the found node's id and its
score (null if not scored), in id order. limit is 1 to 1024; for the next page, pass the last id as
cursor.
| Name | Required | Description | Default |
|---|---|---|---|
| nid | Yes | ||
| limit | No | ||
| cursor | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations the description carries the full safety/behavior burden, and it does disclose a good deal: a read operation (GET), result ordering ('in id order'), null-score semantics, and pagination behavior. It omits any explicit statement of side effects, auth needs, or rate limits, keeping it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with the endpoint front-loaded and no filler. The first sentence is dense with return-format detail, but every clause carries meaning and nothing is wasted.
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 paginated list tool with an output schema, the essentials are covered: result shape, ordering, limit bounds, and cursor-based paging. Nothing critical to invoking it correctly is missing, though it adds no info about auth or defaults beyond the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate and largely does: limit is bounded (1 to 1024) and cursor is defined as the last id for the next page. nid is only implied via the path template rather than explained, so a small gap remains.
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 pairs a specific verb/resource (GET /nodes/{nid}/edges) with a concrete definition of what an edge contains (the found node's id and score). This clearly separates it from get_edge (singular) and list_nodes. It stops short of explicitly naming sibling tools, so it is clear but not sibling-differentiating.
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 provides actionable pagination guidance ('for the next page, pass the last id as cursor') and states the valid limit range, which is genuine usage help. However, it never says when to prefer this over get_edge or list_nodes, leaving the tool-vs-tool decision implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GET /nodes: the grid's nodes, each with its id, key and emb, in id order. limit is 1 to 1024; for the
next page, pass the last id as cursor.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses the HTTP verb (GET, i.e. read-only), the deterministic id ordering, the pagination model, and the returned fields. It omits auth/permission requirements and rate limits, so it is strong 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?
Two sentences, front-loaded with the resource and return shape, then the pagination contract. Every clause carries information the schema does not; nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be spelled out, and pagination, ordering, and bounds are all covered for a simple two-parameter read tool. Only permission/auth expectations are left unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and neither parameter has a description in the schema, yet the description supplies the critical semantics: limit's valid range (1–1024, beyond the schema's bare default of 32) and the exact cursor convention (last id from the previous page). This fully compensates for the documentation gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('the grid's nodes') and even names the payload fields (id, key, emb) and ordering (id order). It is clearly distinguishable in substance from get_node, but it never explicitly contrasts itself with the single-node sibling, which keeps it 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?
Gives concrete operational guidance: limit is bounded to 1–1024 and the next page is obtained by passing the last id as cursor. It does not state when to prefer this over get_node or list_edges, so it is clear context without explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PUT /nodes/{nid}/edges/{eid}: score how well node eid fits query nid, from -1 (wrong) to 1
(perfect), creating the edge if DNA never suggested it, e.g. scores you already have. Only scores train
DNA; a new score replaces the last.
| Name | Required | Description | Default |
|---|---|---|---|
| eid | Yes | ||
| nid | Yes | ||
| score | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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 real behavior: upsert semantics ("creating the edge if DNA never suggested it"), the -1..1 scale, that only scores train DNA, and that a new score overwrites the previous one. It says nothing about permissions, idempotency across identical writes, or error 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?
Single dense sentence that front-loads the action and the score range, but it opens with a redundant REST path ("PUT /nodes/{nid}/edges/{eid}") that adds no selection value, and "e.g. scores you already have" / "Only scores train DNA" are grammatically muddled.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained. For an unannotated mutation tool with 0% parameter coverage the description covers the core mutation semantics (create-if-absent, overwrite), but leaves the id-role confusion and permission expectations unaddressed, so it is only adequate for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and all three parameters are opaque (`nid`, `eid`, `score`). The description gives the score range (-1 to 1) and maps the ids to node/query roles, but the mapping is contradictory with the tool name — `eid` is called a "node" while the tool and endpoint are about an edge — leaving genuine ambiguity about what each id identifies.
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 — recording a fit score for a node/query pair, with the -1..1 range spelled out — which is a distinct action from the structural create_edge/update_edge siblings. It does not explicitly name or exclude those siblings, so an agent must infer the boundary rather than being told.
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?
"creating the edge if DNA never suggested it, e.g. scores you already have" hints at when this is appropriate (recording pre-existing human scores rather than authoring new edges), but there is no explicit when-to-use/when-not-to-use guidance and no routing to create_edge or update_edge. Usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PATCH /nodes/{nid}/edges/{eid}: score a result of query nid that create_edge returned, from -1 (wrong)
to 1 (perfect). Only scores train DNA; a new score replaces the last.
| Name | Required | Description | Default |
|---|---|---|---|
| eid | Yes | ||
| nid | Yes | ||
| score | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses two useful behavioral facts: only scores train DNA, and a new score overwrites the previous one. It omits permission requirements, reversibility, and what the PATCH returns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A compact two-part sentence; the endpoint prefix and semantic range are front-loaded. No wasted filler, though the endpoint notation is arguably redundant with the tool identity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists so return values need not be described, but for a mutation tool with zero annotations and three undocumented parameters, the description leaves gaps around prerequisites and effect scope that would help an agent call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the load. It does clarify the score parameter's range and semantics (-1 wrong to 1 perfect), which is genuinely additive, but nid and eid remain entirely unexplained (e.g., eid's origin, format, or relationship to create_edge's return).
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 action (scoring an edge result) tied to the resource returned by create_edge, with a defined range of -1 to 1. It is distinguishable from list/create/delete siblings, though the mapping from the tool name 'update_edge' to 'score' takes a sentence of parsing.
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 (score results produced by create_edge) and states the replacement rule, but gives no explicit when-to-use/when-not guidance versus put_edge or update_node. The condition for invoking it is inferable but not spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PATCH /nodes/{nid}: change a node. key: a new path, or null to remove it, so the node can no longer be
found; leave it out to keep it. emb: a new embedding; leave it out to keep it. Its scores keep training,
on the new embedding. Returns its id and key.
| Name | Required | Description | Default |
|---|---|---|---|
| emb | No | ||
| key | No | ||
| nid | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full load and does real work: it discloses that setting `key` to null makes the node un-findable (a destructive/orphaning side effect) and that scores continue training against the new embedding, plus it states the return shape. It omits permissions, behavior on a missing node, and embedding dimension constraints, keeping it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the endpoint and resource, then each clause maps to one parameter with no filler sentences. It is somewhat compressed into backtick shorthand, which costs a little readability but wastes no words.
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 mutation tool with no annotations and an existing output schema, the description covers the destructive null-case, the side effect on training scores, and the return keys. Remaining gaps (auth needs, error behavior, embedding constraints) are minor given the output schema already handles the response shape.
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 compensate, and it documents all three params well: `nid` as the path target, `key` as a new path with null=remove and omit=keep, and `emb` as a new embedding with omit=keep. The one weak point is that the schema declares `key` default as "" (empty string) while the description frames removal as null, a subtle mismatch an agent could trip on.
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 up front ('PATCH /nodes/{nid}: change a node'), which is unambiguous about what mutates. It implicitly distinguishes itself from edge siblings by operating on node ids, but never names an alternative (update_edge, delete_node), so separation relies on the reader inferring from the resource noun.
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 explains parameter mechanics but gives no when-to-use vs when-not guidance and never references the neighboring update_edge/put_edge/delete_node tools. An agent must infer the selection criteria entirely on its own.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
create_edgecreate_nodedelete_edgedelete_nodeget_edgeget_gridget_nodelist_edgeslist_nodesput_edgeupdate_edgeupdate_nodeWeb search for AI agents — one tool across 6 engines, routed to the cheapest + cached.
Cloud or self-hosted knowledge for AI agents: hybrid search, reranking, GraphRAG, scoped MCP tools.
LLM-ready web search + instant answers + URL-to-clean-text fetch for agents and RAG.
Agent-native search engine with live web research optimized for AI agents.
Add one secure layer between your agents and this server.
