cwi-discovery-engine

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 usefully discloses the response shape (artist and their tracks with Spotify URLs), which matters because there is no output schema, but it says nothing about authentication, rate limits, or what happens when the name does not match an artist.

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 no filler, front-loading the action first and the payload second. Every clause adds information an agent can act on.

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

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

For a one-parameter, read-only lookup with no output schema, the description covers both the operation and the returned content, which is the key missing structured information. Only the failure/empty-result behavior and the relationship to the search-oriented siblings 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?

There is a single required parameter with 100% schema description coverage, and the schema already includes an example value. The description only restates that lookup is by name, adding no syntax, normalization, or matching semantics beyond the schema, so 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 (look up an artist by name) and adds what comes back (artist plus their tracks with Spotify URLs), so the purpose is unambiguous. It does not distinguish itself from siblings like get_track or search_catalog, which is the only thing keeping 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?

"Look up an artist by name" implies an exact-name retrieval, which is context an agent can use, but there is no explicit statement of when to prefer this over search_catalog, semantic_search, or sync_search. No exclusions or prerequisites are given, so usage must be inferred.

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 returned shape (counts, types, samples) and that it is a bounded summary rather than the whole graph. It does not explicitly state read-only semantics, auth requirements, or size limits, which is the remaining gap for an unannotated 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?

Two compact sentences, front-loading what the tool returns and following immediately with the escape hatch for full data. No redundant or filler 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?

For a zero-parameter read tool with no output schema and no annotations, the description covers purpose, return contents, and the alternative for full data — everything an agent needs 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?

The tool takes zero parameters, so there are no parameter semantics to explain and the baseline of 4 applies. The description correctly implies no filtering or scoping inputs are accepted.

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 ('Summarize') and resource ('the CWI catalog knowledge graph') and enumerates the summary contents (node/edge counts, types, sample nodes). This is clearly distinguishable from the artist/track/search siblings, which operate on catalog entities rather than graph structure.

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

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

It gives a clear selection rule for the full dataset: 'For the full graph, fetch GET /graph.json,' which tells the agent both when this summary suffices and where to go when it doesn't. It stops short of naming a sibling tool as an alternative or stating exclusions, so 4 rather than 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?

No annotations are provided, so the description carries the full behavioral burden. It usefully enumerates the returned fields (title, artist, Spotify URL, genres, moods), but says nothing about read-only safety, auth requirements, or what happens on an ambiguous partial-title match — a real risk given the schema explicitly allows partial titles. It adds value without closing the gaps.

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

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

Two short sentences, zero filler: the lookup semantics come first and the return fields second. Every clause 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 one-parameter lookup with no output schema, the description supplies the essential missing piece — the shape of the return. The remaining gap is ambiguity handling for partial titles, which matters here because partial matching is explicitly permitted.

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% for the single parameter, and the property description already documents exact-or-partial titles plus Spotify ID/URL formats. The description merely echoes that, 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 ('Look up one catalog track') plus the two accepted identifier forms, so the agent immediately knows this is a single-entity lookup. It implicitly contrasts with the multi-result siblings (search_catalog, semantic_search) via 'one ... track', but never names an alternative, so it stops 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?

Usage is only implied: 'by title or Spotify ID/URL' signals the input shape, which suggests this is the tool for a known title or ID. There is no explicit statement of when to prefer it over search_catalog, semantic_search, or sync_search, and no exclusions or prerequisites.

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

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

No annotations are provided, so the description carries the full burden, and it does reasonably well: it discloses the ranking weights (title 3x, genre 2x, mood 1x), the result shape (top 5 tracks with Spotify URLs and matched terms), and a 500-character truncation limit on input. It omits any mention of rate limits, auth, or what happens on zero matches, keeping it below 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?

Three compact sentences, with the core purpose front-loaded before the scoring detail. Every sentence carries information, though the scoring internals are arguably more than an agent needs to select the tool.

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?

There is no output schema, but the description compensates by describing the return payload (top 5 tracks, Spotify URLs, matched terms) and the input truncation behavior. The main gap is the absence of guidance relative to semantic_search and sync_search, which matters given the sibling set.

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

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

Schema description coverage is 100% and the single parameter already documents keywords, examples, and the 500-character cap. The description adds no syntax or format detail beyond that, so the baseline of 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 ('Search the CWI placement catalog by keywords') and adds the scoring model, which tells the agent what kind of search this is. It does not explicitly distinguish itself from the overlapping siblings semantic_search and sync_search, so it stops 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?

Usage is only implied: keyword-style matching is suggested by 'by keywords' and the weighted-match explanation, which hints this is lexical rather than semantic. With siblings named semantic_search and sync_search, the definition should say when to pick this one over those, and it does not.

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 so well: it documents the unsilent degradation path if the Workers AI binding is unavailable, the exact method string ('fallback:keyword') and fallback_note reported in the response, and the fallback's weighting scheme. It also clarifies that fallback scores are never presented as cosine similarity, which prevents an agent from misreading output.

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 purpose is front-loaded and the fallback detail is separated into its own labeled block, so the extra length is largely earned by genuinely unusual runtime behavior. Some phrasing is promotional filler ('the same model that produced the matrix', 'No inference needed on your side; just call this tool') that could be trimmed without loss.

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 tool with no annotations and no output schema, the description does the compensating work by naming response fields (method, fallback_note) and describing the scoring basis. It omits result shape details such as per-result fields or ordering guarantees, which is the main remaining 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 description coverage is 100%, so both q and limit are already documented in the schema (natural-language query, 500-char truncation, 1-20 range, default 5). The description adds no syntax or example beyond the schema's own example. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (semantic search over the CWI catalog embedding matrix) and pins down the mechanism (cosine similarity against 384-dim bge-small-en-v1.5 vectors). An agent immediately knows this is meaning-based retrieval, not keyword matching. It does not, however, name or contrast itself with search_catalog or sync_search, which are the obvious alternatives.

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 'No inference needed on your side; just call this tool' implies it is safe to invoke without pre-embedding, which is useful context. But there is no explicit statement of when to prefer this over search_catalog/sync_search or when-not to use it (e.g. exact-match lookups). Usage is implied rather than routed.

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 add real caveats: descriptors are editorial/curated by CWI Sync and BPM values are estimates rather than audio analysis. That provenance warning is valuable for interpreting results, though nothing is said about auth, rate limits, or result size.

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-sentence block that front-loads the verb and resource before the qualifiers. Dense but every clause (catalog size, descriptor types, provenance caveat) 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 search tool with no output schema, the description explains the catalog's contents but never describes the return shape, result count, or pagination behavior. The domain framing is good, yet the response contract is left implicit.

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 parameter already documents the format, examples, and 500-character truncation. The description's example queries ('fight scene') are consistent with the schema but add no syntax or format detail beyond it, so 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+resource ('Search the CWI sync catalog') and scopes it to a concrete domain (23 tracks with editorial sonic descriptors) for music-supervision queries. It does not, however, distinguish itself from siblings like search_catalog or semantic_search, leaving the agent to infer the difference.

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?

Example queries ('fight scene', 'neon city') imply the intended music-supervision use case, but there is no explicit when-to-use versus search_catalog or semantic_search, and no exclusions. 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.