Hashgrid DNA

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

With no annotations, the description carries the full load and does well: it discloses that the returned api_key is shown only once, how to present it (api_key argument or Authorization: Bearer hg-… header), the max_items capacity, and a per-address daily creation rate limit. It does not say what happens on failure or what the grid contains by default.

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 action, then the api_key caveat, then capacity and rate limits. Dense but each clause contributes; the 'POST /:' prefix is minor noise.

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 and the auth/capacity/rate-limit behavior is covered, so the hard parts are present. The gap is the undocumented `name` parameter, which an agent cannot interpret from the description or 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?

There is one parameter (`name`, defaulting to 'hashgrid') at 0% schema description coverage, and the description never mentions it. The single parameter an agent must reason about is documented in neither place.

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 specific verb and resource ('create a grid') and adds scope the name alone doesn't convey: it is 'your own store of items.' That distinguishes it from the item/query/grade siblings, though it never explicitly contrasts with them.

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

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

The 'no API key needed' clause plus 'pass it as api_key to every other tool' implies this is a bootstrap step that must precede other calls, which is useful sequencing guidance. It stops short of stating when-not to create a grid (e.g. reuse an existing one) or pointing at get_grid/list_items 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 does disclose useful behavior — the operation is synchronous ('its results are ready at once') and re-creation should be avoided so grades accumulate. It omits auth expectations despite an api_key parameter, and says nothing about failure modes or whether content is validated.

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, and every clause contributes something (return value, id reuse, result timing). The phrasing 'its content as put_item takes it' is slightly indirect and costs the reader a lookup.

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 little explanation, and the description adds the key fact that the id is the handle for other query tools. Still, for a mutation-style create with no annotations and no schema descriptions, leaving `type` and `api_key` undocumented leaves the definition under-specified.

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 explain all three parameters. It only characterizes `content` ('a question to ask of the items, its content as put_item takes it', a cross-reference requiring knowledge of a sibling schema) and leaves `type` and `api_key` entirely unexplained.

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 ('POST /queries: store a question to ask of the items') and discloses the return value ('its `id`'). It implies the relationship to siblings by saying the other query tools take that id, but never names get_query/delete_query/get_results to disambiguate directly.

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 line 'ask again with the same `id` rather than creating the same query twice, so its grades add up' is genuine when/when-not guidance about reusing ids. However, it gives no guidance on when to create a query versus using put_grade/get_results, nor on prerequisites such as api_key.

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 supplied, so the description carries the full behavioral burden, yet it says nothing about whether the deletion is permanent, whether it is idempotent, what happens if no grade exists, or that an api_key is needed for authentication. 'Forget' gestures at removal without specifying consequence.

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 with the route first and the effect second; nothing is padded. The raw path string partially duplicates the prose, but not enough to be wasteful.

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 described, but for a destructive mutation with no annotations and zero parameter documentation, the description should state irreversibility, auth requirements, and parameter meanings. It leaves those critical gaps open.

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 all three parameters need explanation. The description only implies 'id' is the query id and leaves 'key' vague ('the item at key'), and never mentions the api_key parameter at all—too little for full compensation of the coverage 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?

The description names a specific verb plus resource ('DELETE ... grades'), and by including the item key it scopes the operation to a single grade rather than the whole query. It is distinguishable from get_grade/put_grade by the verb alone, though the informal 'forget' phrasing is slightly weaker than 'delete'.

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 when-to-use or when-not-to-use guidance, no mention of how this relates to put_grade (upsert?) or list_grades, and no prerequisites. The CRUD name implies usage, but the description itself adds no routing information.

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 supplied, the description carries the full burden and does real work: it discloses the destructive cascade (items, queries and grades are removed too) and the downstream consequence that the grid's key stops working. It stops short of stating irreversibility or any permission/auth requirement, which matters for an unannotated destructive 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?

One dense sentence that front-loads the destructive action and the blast radius before the side effect. The 'DELETE /:' prefix is wasted routing jargon, but the rest earns its place.

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

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

For a destructive, unannotated tool the description covers the blast radius well and an output schema exists to explain return values, so the major gaps are the unresolved api_key meaning and the absence of any reversibility or authorization statement.

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 single parameter api_key has 0% schema description coverage, so the description must compensate and does not. The phrase 'its key stops working' hints at key semantics but leaves it ambiguous whether api_key is the caller's credential or the grid's key being invalidated — a consequential ambiguity for a deletion tool.

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 the grid') and immediately scopes it against the sibling deletes by naming what else is destroyed: 'items, queries and grades'. An agent can distinguish this from delete_item, delete_query and delete_grade 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?

The cascade warning implies this is the heavyweight option versus the granular delete siblings, but the description never explicitly says when to choose this over them or what preconditions apply. Usage is inferable rather than stated.

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

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

With no annotations, the description carries the full burden, and it does disclose the important cascade behavior that deleting an item also removes every grade of it. It says nothing about irreversibility, required authorization, or what happens when the key does not exist, which leaves meaningful gaps for a destructive 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?

One short sentence with the destructive scope front-loaded; nothing is padded. The 'DELETE /items/key:' prefix is redundant HTTP framing that adds noise rather than 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?

An output schema exists, so return values need not be explained, and the cascade is covered. For a destructive tool with no annotations, an undocumented auth parameter, and no error or irreversibility notes, the description is adequate but not 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 description coverage is 0%, so the description must compensate for both parameters. It gives partial meaning for `key` as the item identifier, but `api_key` is never mentioned at all, leaving an agent to guess that it is a credential and where it comes from.

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 ('delete the item at `key`') and adds the cascade scope ('and every grade of it'), which implicitly separates it from the sibling delete_grade. The leading 'DELETE /items/key:' is route notation rather than a clearer statement of purpose, but the intent 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?

There is no explicit guidance on when to use this versus delete_grade or delete_grid, and no stated prerequisites or exclusions. The cascade hint is the only inference an agent can draw about the choice between siblings.

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 supplied, the description carries the full burden, and it does disclose one important behavioral trait: deleting a query also removes its grades (a cascade). It does not state irreversibility, permission requirements, or that an API key is needed to authenticate, which a destructive tool should surface.

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 naming the endpoint and the effect. The REST path prefix is mildly redundant but it is short and 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?

An output schema exists, so return values need not be explained, and the cascade to grades is covered. However, for a destructive mutation with no annotations and an undocumented auth parameter, the description should do more about irreversibility and credentials.

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 two parameters. The description identifies `id` as the query identifier, but the `api_key` parameter is completely undocumented in both schema and description, leaving the agent to guess how authentication is supplied.

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 — 'delete the query `id`' — and adds the side effect that its grades go with it. It is unambiguous, though it does not distinguish this tool from other deleters such as delete_node in the sibling set.

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

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

There is no guidance on when to use this versus delete_node or other cleanup paths, and no stated preconditions or exclusions. The agent is left to infer that this is for removing queries permanently.

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 supplied, so the description carries the full burden. The 'GET' prefix weakly signals a read operation, but there is no mention of authentication (despite an `api_key` parameter), what happens when no grade exists for the key, or whether the value is cached/derived.

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 a single short sentence with no padding, but the 'GET /queries/id/grades/key:' prefix is route boilerplate that consumes the most prominent position without adding agent-relevant 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?

An output schema exists, so return values need not be described, but for a 3-parameter tool with zero schema coverage the definition should still clarify parameter meaning, auth expectations, and the not-found case. Those gaps make it inadequate for correct invocation in ambiguous situations.

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. It only loosely implies that `id` is a query identifier and `key` is an item key; formats, whether `id` is a query name or ID, and the role of the optional `api_key` are all left undocumented.

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 the resource (a grade) and its scope (the grade of the item at `key` within a query), so the basic purpose is inferable. However, it leads with a raw REST route rather than a clear verb+resource statement, and it never says what distinguishes this from `list_grades` or `get_results`.

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 is given. With siblings like `list_grades`, `put_grade`, and `delete_grade` present, an agent gets no help deciding when to fetch a single grade versus listing them, and no prerequisites or exclusions are stated.

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

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

With no annotations, the description carries the full burden: it does establish read-only semantics via 'GET' and explains what max_items means (queries counted, null = no limit), which is genuinely useful. It says nothing about authentication failure, what happens if api_key is omitted (the schema default is null), or whether an invalid key errors versus returning an empty 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?

One front-loaded sentence with no filler; the parenthetical clarifying max_items semantics earns its place. Minor waste in the 'GET /:' route echo, which adds little for an agent that already knows 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?

An output schema exists, so return-field enumeration is not required and the description is largely sufficient for a trivial single-resource read. The notable omission is the optional/null api_key behavior, which neither the schema nor the description resolves.

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% for the single parameter, api_key, so the description must compensate. It does convey that the key determines which grid is returned ('the grid the API key opens'), which is real added meaning. It does not explain the null default or any key-format expectation, leaving a 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?

Names a specific read operation (GET) on a specific resource (the grid opened by the API key) and enumerates the fields returned, name and max_items. An agent can distinguish it from get_item/get_grade/get_query, which target subordinate resources. It stops short of a crisp sentence like 'Retrieve the grid's metadata', but the intent 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?

There is no explicit when-to-use guidance, no mention of alternatives such as list_items or get_query, and no stated prerequisites. A reader infers this is the metadata call to make before creating items or queries (to check the max_items limit), but that inference is left entirely to the agent.

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 supplied, so the description must carry the burden. It does disclose read-only behavior via 'GET' and clarifies content format by reference to put_item, but omits auth/api_key handling and not-found 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 single sentence is appropriately short and front-loaded, but the route-notation style 'GET /items/key:' is terse and slightly awkward for an agent-facing description.

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

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

Although an output schema exists to describe returns, the definition remains incomplete: it lacks when-to-use guidance, explains only one of two parameters, and has no annotations to compensate for the missing auth and error semantics.

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%. The description clarifies that `key` identifies the item and that `content` matches put_item's input, but it says nothing about the `api_key` parameter.

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

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

States a specific retrieval operation: 'GET /items/key: the item at `key`'. It clearly implies single-item retrieval with content matching put_item, which distinguishes it from list_items somewhat, but doesn't explicitly contrast with 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?

Provides no guidance on when to use this versus list_items or other getters, and no prerequisites or error conditions. The read intent is only implied by 'GET'.

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 supplied, so the description carries the full disclosure burden. The 'GET' prefix reasonably signals a read-only operation and the create_query round-trip detail is genuinely useful context beyond the schema. However, it says nothing about authentication requirements (despite an api_key parameter), not-found behavior, or permissions, which are the main behavioral gaps for a lookup 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?

A single compact sentence with the resource and identifier front-loaded and no filler. It is arguably over-compressed for a tool with an undocumented auth parameter, but every word present earns its place.

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

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

An output schema exists, so return values need not be described, and the create_query reference covers content shape. Still, with zero annotations and zero schema coverage, the description leaves the api_key parameter and error/auth behavior entirely unexplained, which is a meaningful omission for a two-parameter tool.

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

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

Schema description coverage is 0%, so the description must compensate for both parameters. It adds some meaning for `id` by framing it as the query identifier that yields the content create_query takes, but `api_key` is never mentioned, leaving the agent with no explanation of how authentication is supplied. Half the parameter surface is undocumented in both schema and description.

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

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

The description names a specific verb and resource (GET /queries/id) and pins the scope to a single query identified by `id`, which cleanly separates it from siblings like get_grid and get_node. It also cross-references create_query to define the shape of `content`, so an agent knows what comes back. It stops short of a plain-language statement of intent, but 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?

There is no guidance on when to call this versus alternatives, and no sibling covers a query-list case to contrast with, so the agent must infer that this is the single-item fetch. The only relational hint is that `content` matches what create_query accepts, which is about format rather than tool selection. No preconditions or exclusions are stated.

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

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

With no annotations supplied, the description carries the full burden and does substantial work: it discloses sort order (best first), the meaning and provisional nature of `score` (only ordering is meaningful before the grid has grades), that items are returned without content, and that results adapt to grades within seconds. It omits pagination/limit behavior and any auth expectations, so it is not complete.

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 content is front-loaded: the endpoint and what is returned come first, then the score semantics, then the filtering flag and the follow-up workflow. It packs a lot into a few clauses, though the long run-on sentence with nested parentheticals is harder to parse than it needs to be.

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-shape detail is not strictly required, and the description still clarifies sorting and score interpretation. But for a five-parameter, no-annotation tool it leaves `limit` and `api_key` undefined and says nothing about result-set size or failure modes, so it is only adequate.

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. It explains `prefixes` with an example and default ("all items by default") and explains `ungraded` as excluding already-graded items; `id` is implied by the path shown. However `limit` (default 32) and `api_key` are never explained anywhere, leaving real 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 names a concrete verb/resource: it returns a query's best-matching items, best-first, each with a score, and explicitly frames the output as what list_items shows but without content. That distinguishes it from the generic list_items sibling. It is dense and backtick-laden rather than plainly stated, which keeps it from 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?

Usage is implied rather than stated: `ungraded` exists for the case where you have already graded items, and the final sentence tells the agent to grade results with put_grade so the results improve within seconds. There is no explicit 'use this when / not when' framing and no direct comparison against list_items or get_item as 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?

No annotations are provided, so the description must carry the full behavioral burden. It implies a read-only GET and mentions path order, but omits authentication requirements for api_key, pagination behavior, error conditions, and any other operational context.

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

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

The description is short and front-loads the endpoint, but it wastes words on redundant phrasing ("grades, the query's grades") and remains cryptic rather 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?

An output schema exists, so return fields need not be explained. However, for a two-parameter tool with no annotations and no schema parameter descriptions, the definition is missing essential input guidance and usage context.

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

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

Schema description coverage is 0%, so the description should compensate. It only indirectly references the required id via the path, and it says nothing about the optional api_key parameter or the expected format of id.

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 identifies a GET operation returning a query's grades with key/score, but the phrasing is awkward and repetitive ("grades, the query's grades") and does not clearly distinguish it from sibling tools like get_grade or list_items.

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 guidance on when to use this tool versus alternatives such as get_grade for a single grade, nor any exclusions or prerequisites. Usage is only implied by the HTTP verb.

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 load: it discloses that results are sorted by key, that item contents are omitted, that the page size is capped at 100 (default 32), and how pagination terminates. It is silent on authentication despite an `api_key` parameter and says nothing about rate limits 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?

Three dense clauses with no filler, front-loading the resource and scope before filtering, paging, and the get_item pointer. The backticked field names make it scannable despite the telegraphic style.

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 four-parameter list tool with an output schema already covering return values, the description supplies the meaningful behavior (ordering, content omission, paging) an agent needs. The only real gap is authentication guidance around `api_key`, which is undocumented everywhere.

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: it gives `prefix` semantics with an example ("tools/") and its default of all items, the `limit` range 1-100 with default 32, and the `after` cursor's origin and null termination. The `api_key` parameter is never mentioned in either schema or description.

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

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

States a specific verb and resource (list `items`, keys starting with `prefix`, in key order, without content) and explicitly contrasts with the sibling get_item, which reads a single item's content. An agent can pick between list_items, get_item and put_item 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?

Names the alternative (get_item) and its selecting condition, and explains the paging loop: pass the returned `next` as `after`, null means last page. No explicit when-not-to-use beyond that, but the routing 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?

With no annotations, the description carries the full burden and does disclose two important traits: the grade trains DNA (a side effect beyond simple storage) and replaces any prior grade (overwrite, not append). It omits permission/auth expectations and doesn't mention failure behavior, but the overwrite and training side effects are the non-obvious facts an agent most 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?

Front-loads the route and the operation, then the scoring scale, then the workflow hint — a sensible ordering with little waste. The repeated route notation and parenthetical example are slightly verbose but each 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?

For a mutation tool with an output schema (so return values needn't be explained) and 4 parameters, the description covers the operation, the value scale, the overwrite behavior, and the training side effect. The remaining gap is the undocumented `api_key` parameter and any auth constraints, which is notable but not fatal.

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 supply meaning and it does for the two critical parameters: `key` is defined as get_results' identifier format (e.g. "42") and `score` gets an explicit -1 to 1 scale with partial-credit semantics. `id` is inferable as the query id from the route, but `api_key` is never addressed, which keeps this short of a 5.

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 (grade) and resource (the item at `key` for query `id`), and the name plus description together cleanly separate it from get_grade, list_grades, and delete_grade. The agent can tell exactly what operation is performed without opening the schema.

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

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

"Grade the results you judged, typically the first few" gives a clear usage context and ties the key value back to get_results, so the agent knows the call follows a results-review workflow. It doesn't explicitly state exclusions (e.g. that re-grading overwrites rather than appends is mentioned, but no guidance on when to delete versus re-put), leaving a small gap.

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

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

With no annotations, the description carries the full burden and discloses important behavior: overwrite/upsert semantics, 8 KB content limits, image conversion to WebP at max 512 px, embed retention behavior, and returned fields. It omits authentication requirements, error behavior, and some mutation details, but is otherwise rich.

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 operation and key format, and most sentences carry specific, relevant information about content types and constraints. It is dense and somewhat jargon-heavy, but there is little obvious waste for a tool with this much content-type behavior.

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, but the description still summarizes returned fields. It covers content formats, type rules, key grouping, and embed handling well; the main gap is the undocumented api_key parameter and lack of auth/error context.

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

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

Schema description coverage is 0%, so the description must compensate; it explains key format and prefix grouping, content formats for text/record/image/emb, and the allowed type values plus when to omit type. It does not mention the api_key parameter at all, leaving one parameter undocumented in both schema and description.

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

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

The description opens with 'PUT /items/key: write the item at key', naming a specific verb and resource, and clarifies that it creates or replaces content. That makes the upsert behavior distinct from read/delete/list siblings without needing their definitions.

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 usage context by saying the tool creates or replaces the item at a key, and it adds guidance about grouping items under prefixes. It does not explicitly name sibling alternatives or state when not to use this tool, so it falls short of full when/when-not guidance.

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