nope-mcp — Open Educational Resources search

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

Annotations already declare this a safe, idempotent, closed-world read, so the safety profile carries no burden here. The description adds one useful return-content hint ('with resource counts'), but says nothing about pagination behavior despite the limit cap of 100, nor about how the language parameter affects output labels.

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 well-formed sentence that front-loads the verb and resource and includes a return-shape note. No filler and nothing buried.

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

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

With no output schema, the description should carry more weight on return contents; it gives only the vague phrase 'with resource counts' and does not describe what fields each level entry has or that labels vary by language. It is serviceable but leaves real gaps for a tool an agent must interpret results from.

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 limit and language are fully documented in the schema and the baseline is 3. The description contributes no additional parameter semantics 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 ('List') and resource ('educational levels') and even enumerates examples (Primary, Secondary, Higher Education), so the agent knows exactly what comes back. It does not, however, differentiate itself from close siblings like browse_subjects or browse_resource_types, which follow the identical browse-a-vocabulary pattern.

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

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

The description gives no when-to-use, when-not-to-use, or alternative guidance, which is a notable gap given four sibling 'browse_*' tools that an agent could easily confuse. Usage is only implied by the word 'List'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is fully covered structurally. The description adds that each entry includes a resource count, which is useful return-content context, but says nothing about ordering, pagination beyond the limit param, or how the language setting affects 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?

A single front-loaded sentence that states the action, the enumerated resource, examples, and the payload. No filler or redundancy.

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, annotation-covered, no-output-schema browse tool, the description conveys what is returned and to what degree (types with counts). It omits the label-localization behavior tied to the language parameter, which is a minor gap given the schema documents that parameter.

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 parameters (limit, language) are already documented with defaults, bounds, and meaning. The description adds no syntax or format detail beyond what the schema provides, 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 (List) and resource (learning resource types) and even gives examples (Video, Course, Worksheet) plus the payload detail (resource counts). It is clearly distinguishable in substance from search_resources, but it does not name or contrast itself with the parallel browse_educational_levels / browse_subjects 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?

The verb 'List available' implies a browsing/enumeration use case, but there is no explicit when-to-use, when-not-to-use, or routing to alternatives such as search_resources for filtered queries. Usage is left to inference from the name and the parallel browse_* 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by disclosing the return shape ('labels and resource counts'), which matters because there is no output schema, but it says nothing about pagination behavior or how limit/prefix/language affect results.

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 zero waste; the purpose is front-loaded before the return-shape detail, and nothing is repeated from the title or schema.

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 no-required-parameter read tool with full schema coverage and safety annotations, the description covers purpose and return contents adequately. The only omission is any guidance on default behavior (e.g., the de language default and 50-item limit) or how to page through large subject lists, which are minor given the schema documents them.

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% with all three parameters (limit, prefix, language) documented in the schema, so the schema carries the burden. The description adds no parameter-level detail beyond the implicit 'labels' reference, making the baseline 3 correct.

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 ('List available subjects/topics') and scopes it to the educational resource collection, which cleanly separates it from siblings like browse_resource_types and browse_educational_levels. It stops short of explicitly naming the sibling it is not, so it is clear but not maximally 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?

The phrase 'available subjects/topics in the educational resource collection' implies the browsing/discovery context, but there is no explicit when-to-use versus alternatives, no exclusions, and no mention of how this differs from sibling browse tools or from search_resources. 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?

Annotations already declare readOnly, idempotent, non-destructive, non-open-world behavior, so the safety profile is covered. The description adds genuinely non-obvious behavior: lookups are not license-filtered, non-resource kinds return their search-result shape, and openLicense is defined against the current search filter. Return-format detail is thinner, but the added context is substantive.

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?

Four sentences, front-loaded with the retrieval keys before the return-shape and license caveats. Dense but each sentence carries distinct information; the closing markdown-link rendering instruction is slightly advisory but still actionable for an agent preparing output.

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

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

With no output schema, the description compensates by describing what different lookup modes return, the license field semantics, and how to surface the result to a user. Nothing essential for a correct single-fetch call is left unstated.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: it marks naddr as the preferred handoff from search_content and constrains relays to those returned by list_relays. The author parameter's disambiguation role is echoed rather than expanded, keeping it 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?

The first sentence states a specific verb (Retrieve), resource (a single piece of content), and three lookup keys with a stated preference order. It also explicitly frames itself as the handoff target for search_content results, separating it from the sibling search tools.

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 names when to use naddr (preferred, from a search_content result), when to fall back to d-tag or eventId, and when to pass relays (only those from list_relays). The condition selecting each path is explicit, including the author param for disambiguating duplicate identifiers.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and a closed-world scope. The description adds meaningful context beyond that: the data origin (NIP-51 kind 30000 follow sets) and the shape of what comes back (names, pubkeys, NIP-05 identifiers).

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

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

Three short sentences, front-loaded with the core action, then the return fields, then the actionable next step. No filler or repetition.

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

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

With no output schema and no parameters, the description carries the return-value burden and does so: it names the fields returned and how to consume them. Nothing an agent needs to invoke it correctly is missing.

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 the baseline is 4. The description correctly notes there are no filters and instead describes the return payload, which is the only semantic an agent needs here.

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 known calendar event authors') plus the data source (configured follow sets, NIP-51 kind 30000). This distinguishes it from the similarly named sibling list_known_authors by anchoring the scope to calendar follow sets.

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?

Explicitly tells the agent what to do with the output: use the pubkeys with search_calendar_events(authors: [...]). It lacks an explicit 'when not to use this' (e.g., vs list_known_authors), but the follow-up workflow is spelled out clearly.

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

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

Annotations already declare the safe-read profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds genuinely useful context the annotations do not: the origin of the data (configured NIP-51 kind 30000 follow sets) and the concrete fields returned (names, pubkeys, NIP-05 identifiers). It does not discuss staleness or what an empty list means.

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

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

Three short sentences, each doing distinct work: what it lists and where from, what it returns, and how to use the result. Purpose is front-loaded, no filler or restatement of the title.

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

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

With no output schema, the description compensates by enumerating the returned fields and the downstream usage pattern, which is what an agent needs. Minor gaps remain around empty/degraded results and refresh behavior, but it is sufficient to invoke 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 the baseline is 4 and there is nothing for the description to disambiguate. The mention of authors: [...] refers to search_resources' parameter, not this tool's inputs, so it does not mislead.

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 ('List known educational resource authors') plus the data source ('loaded from configured follow sets (NIP-51 kind 30000)'), which distinguishes it from siblings like list_calendar_authors and resolve_author. An agent can identify this as the local-curated author list without opening anything else.

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?

Explicitly routes the agent forward: 'Use the returned pubkeys with search_resources(authors: [...]) to filter resources by author.' This gives clear downstream context, but it does not say when NOT to use it or why an agent would pick it over resolve_author or list_calendar_authors when looking for an author.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds real behavioral context beyond that: which relay set is hit on every query versus only on explicit opt-in, which is the key consequence of a relay's classification. Return shape is not described.

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

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

Two tight sentences, front-loaded with the purpose and then the semantics. Nothing is redundant or padded.

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-only listing tool with no output schema, the description supplies the domain meaning an agent needs to act on the result. It stops short of saying what the returned entries look like or how they relate to the relay_list_get sibling.

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 the baseline is 4. The description nonetheless gives meaning to the values the tool yields (defaultRelays vs extraRelays) and how those values feed a parameter on other tools, which is useful framing.

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 the configured AMB relays") and immediately explains what the two relay categories are. It does not, however, distinguish itself from the near-named sibling relay_list_get, so an agent cannot rule out overlap from the description alone.

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?

Explains the operative distinction: defaultRelays are always searched, extraRelays (e.g. OERSI) only when explicitly passed to a search/get tool. That implicitly tells the agent when this tool matters (before choosing relays for a query). No explicit when-not-to-use or sibling alternative is given.

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

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

Annotations already declare readOnly, idempotent and non-destructive behavior, so the safety profile is covered. The description adds genuine value beyond that: it names the return content (read and write relays), the underlying kind (10002), and the signer-fallback behavior, which matters because there is no output schema.

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

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

Three short sentences with no filler, and the core identity (NIP-65 relay list, kind 10002) is front-loaded before the return values and fallback rule. Every sentence 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 single-optional-parameter read tool with no output schema, the description covers identity, return shape, and the parameter default. It is nearly complete; only the relationship to the sibling 'list_relays' is 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 100% and the single parameter is already documented as defaulting to the connected signer. The description restates this default rather than adding syntax or format detail, so the baseline of 3 is appropriate.

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 with extra precision: 'Get a user's NIP-65 relay list (kind 10002)' and clarifies it returns read and write relays. This is far more informative than the bare name, but it never distinguishes itself from the sibling 'list_relays', leaving the agent to guess which one to pick.

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 supplies a useful conditional: 'If no pubkey provided, uses the connected signer's pubkey,' which tells the agent when the parameter can be omitted. However, it gives no guidance on when to use this tool versus 'list_relays' or 'relay_stats', so the usage context is only implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds that the set includes both 'default and extra' relays and names three returned fields, which is useful but thin given there is no output schema to carry return-value detail.

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 no wasted clauses; the verb leads and the returned fields follow. Slightly generic phrasing ('Get information about') keeps it from being maximally crisp.

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

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

With no output schema, the description must carry the return-value burden, and it only lists three fields without indicating structure, count, or ordering of the relay list. For a zero-parameter read tool it is adequate but not fully self-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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly implies a no-argument, whole-collection call and adds nothing misleading about inputs.

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 clear verb and resource ('Get information about all selectable AMB relays') and enumerates what is returned (supported NIPs, relay name, description). It does not, however, distinguish itself from the closely related siblings list_relays and relay_list_get, leaving ambiguity about which relay-inspection tool to pick.

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 guidance, no prerequisites, and no mention of the sibling relay tools (list_relays, relay_list_get) that appear to overlap in purpose. The agent must infer the selection criteria entirely.

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

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

Annotations only cover safety (read-only, idempotent). The description adds real behavioral context beyond that: it explains the underlying mechanism (kind-0 index / NIP-50 search), that results are multiple candidates ranked by relevance, that coverage is limited to authors who published here, and that a wrong pick yields empty results rather than an error.

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

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

Front-loaded with the core action and the workflow, then the caveats. It is long and the community-pubkey discussion is somewhat digressive, but each part carries real routing value, so it mostly earns its length.

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

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

No output schema exists, yet the description tells the agent what comes back (ranked candidate pubkeys) and how to use them, plus the coverage limitation and the empty-result failure mode. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and both params are self-documented, so the baseline is 3. The description reinforces the semantics of `name` (name-driven disambiguation, org or person) but says nothing extra about `limit` beyond the schema.

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

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

States a specific verb+resource ('Resolve an org or person NAME to candidate pubkeys') and immediately distinguishes itself from siblings list_known_authors and search_content. An agent can tell exactly what it does and what it feeds into.

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 an explicit workflow (resolve_author → pick candidate → search_content({authors:[pubkey]})), names the alternative it differs from (list_known_authors), and states the key when-NOT case: it does not resolve a community's kind-10222 pubkey. This is about as complete as usage guidance gets.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real behavioral context: it is a free-text search, the exact-match filter failure mode, and that results include the matching field plus a resource count. It stops short of describing result ordering or pagination.

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?

Four sentences, each earning its place: purpose, the exact-match rationale with a concrete example, the return contents, and the sibling distinction. Purpose is front-loaded and there is 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?

With no output schema, the description carries the return-value burden and does so (similar names, the field they appear in, a resource count). Combined with the filter failure-mode explanation and sibling routing, nothing needed to call it correctly is missing.

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 the schema already documents both parameters. The description reinforces the free-text nature of `name` but adds no syntax or format detail beyond the schema, 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 ("Resolve an actor name ... to the EXACT spelling used in the AMB metadata") and gives the downstream purpose. It explicitly names and contrasts the sibling resolve_author, so an agent can distinguish the two without opening either 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?

Tells the agent exactly when to use it — before passing names to the publisherName/creatorName filters of search_resources — and why (exact full-string match causes silent misses). It also states when NOT to use it by routing Nostr signing accounts to resolve_author.

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

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

Annotations already declare readOnly/idempotent/non-destructive and openWorld=false, so the safety profile is covered. The description adds real behavioral context beyond that: results come from 'the configured calendar relay' (a closed, specific data source), and it discloses output-field relationships (url vs sourcePage) plus a hard constraint that the agent must never synthesize an naddr or viewer URL itself.

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?

Capability statement is front-loaded in the first two sentences, and the rendering guidance follows. The rendering instructions are arguably tangential to invoking a search tool, but they encode a real correctness rule, so the length is mostly earned.

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

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

With 13 optional parameters, a 100%-covered schema, and no output schema, the description supplies what the schema cannot: the data source, the usable output link fields, and the anti-hallucination rule for constructing links. It would be more complete with explicit sibling routing, but it is sufficient 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 100%, so every one of the 13 parameters is already documented, including kinds defaults, timestamps, and the geohash-vs-query/community caveat. The description only restates the filter categories generically, adding no syntax or default information beyond the schema — the baseline 3 is appropriate.

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 ('Search for NIP-52 calendar events') and even splits the resource into its two subtypes (date-based 31922 / time-based 31923), which is enough to distinguish it from generic search_content or search_resources siblings. It stops short of naming or contrasting those siblings explicitly.

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 lists the supported filter dimensions (temporal, geohash, hashtag) but never states when to choose this tool over the sibling search/content tools, nor any prerequisite. The genuinely useful routing rule ('a geohash query forces the location index and ignores topic; filter client-side') lives in the schema's query/community params rather than in the description. Usage is implied rather than guided.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial context beyond them: license-gating behavior for resources, server-side NIP-50 filter resolution, semantic passage ranking with snippet attachment, and the eventAuthor-vs-publisher distinction with an explicit warning not to conflate them.

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 core verb/resource and organized by concern (types, licensing, intent routing, fields, rendering). It is long and dense, but nearly every sentence carries operational information; a little tightening of the license and rendering guidance would help.

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

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

No output schema exists, so the description must cover return values, and it does: interleaved ranked results, snippet passages, eventAuthor/creator/publisher fields, and the sourcePage > url > naddr rendering preference. An agent has everything needed to call and present results.

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

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

Schema coverage is 100%, so 3 is the baseline, but the description adds meaning the schema does not carry: the query string can embed NIP-50 field filters (type:, doi:, keywords:, partOf:) resolved server-side, and it explains what the authors/community params reference (resolve_author output) and the actor-dilution pitfall for query.

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 (topic search across all content types) and enumerates each type with its kind number (30142, 30023, 30818, 30143, 30144, 30040/30041). It is immediately distinguishable from search_resources, search_passages, and search_calendar_events.

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?

Explicitly splits DISCOVERY intent (browse materials) from QUESTION intent (build an answer) and routes the latter to search_passages, with follow-up to search_calendar_events for events and resolve_author for actor-constrained searches. When-to-use and when-not-to-use are both 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?

Annotations already cover read-only/idempotent/non-destructive, but the description adds substantial behavior the annotations do not: results capped at two passages per document, snippet-only passages lacking fulltext, license filtering only for educational resources, and typed failure modes ('Fails rather than widening scope'). It also discloses the $me/$contacts resolution and the canonical-spell return value.

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 core classification ('THE DEFAULT TOOL FOR QUESTION-SHAPED QUERIES') and every sentence carries operational content for an 11-param tool. It is dense — a single long paragraph heavy with parentheticals — which costs some readability, but there is little wasted text.

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

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

For a complex, 11-param tool with no output schema, the description covers what is returned (passages with citations: source resource, page, heading, source URL), how to answer from results, scope construction, spell substitution, and error behavior. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100% and the schema already documents the search/authors split, so much of the routing advice is reinforcement. However, the description adds genuinely new guidance absent from the schema — 'Keep `question` topic-only' and phrasing it as a topical statement rather than the user's literal sentence — plus concrete kinds examples. It adds value beyond the schema, though not dramatically.

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+resource ('retrieves the best-matching fulltext passages from the corpus') and a clear scope statement ('THE DEFAULT TOOL FOR QUESTION-SHAPED QUERIES'). It explicitly distinguishes itself from search_content by intent (question-shaped vs discovery), so an agent can pick between siblings without opening either 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?

States when to use it (question-shaped queries like 'wie/warum/was hilft bei X?'), when to use the alternative ('For discovery intent — use search_content instead, or afterwards to offer browsable links'), and how to route source restrictions into scope params. Prerequisites like the required-but-simple scope and the relay_unreachable retry path are spelled out.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered; the description still adds real behavior beyond that: the licensing filter on results, the exact-string (non-fuzzy) filter semantics that fail silently, and the actorCandidates fallback returned on a zero-match actor filter. That is genuinely useful operational context not present in any structured field.

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

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

Front-loaded with purpose and scope, then the exact-match caveat, then the zero-match recovery path — a logical order with no filler sentences. It is somewhat dense and the exact-match point is repeated, but every sentence carries information an agent needs.

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 12-parameter, no-required-args, no-output-schema search tool, the description covers scope, filter semantics, and the zero-match recovery behavior. It stops short of describing the general result shape or pagination (limit is capped at 250 but ordering/paging behavior is unstated), 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 the baseline is 3; the description earns more by explaining that the metadata filters are exact case-insensitive full-string matches rather than substring searches, and by pointing to resolve_publisher for canonical spellings. It does not add semantics for query, since/until, relays, or authors, but the high-coverage schema already handles those.

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 educational resources), enumerates the two search modes (full-text and metadata filters), and pins the scope with an explicit inclusion/exclusion rule (only CC0/PD/CC BY/CC BY-SA returned). An agent can distinguish it from search_content or search_passages by the openly-licensed constraint alone.

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?

Clear context plus concrete routing: call resolve_publisher before actor filters, and use browse_subjects/browse_resource_types/browse_educational_levels for valid labels. It also warns that a guessed spelling silently returns 0 results. It does not, however, contrast itself against the other search_* siblings, so the alternative-selection guidance is incomplete.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered without the description. The description adds value only by disclosing the shape of the payload (broader/narrower/related), which matters because there is no output schema; it says nothing about missing-URI behavior or label-language fallback.

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 sentence that front-loads the action and resource, then lists the returned relations. No filler, no restatement of the title, nothing that fails to earn 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?

With no output schema present, the description usefully summarizes the returned concept relations, and the annotations cover the safety profile. For a two-parameter read tool this is nearly complete; only the language-fallback behavior and error case for an unknown URI are 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 100%, so both 'uri' (with an example) and 'language' (with examples) are already documented in the schema. The description contributes nothing extra about parameter semantics, 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?

The description names a specific verb and resource ('Get details of a single SKOS concept by its URI') and enumerates what the result includes (broader, narrower, related). It is clearly distinguishable from skos_search (search) and skos_get_vocabulary (whole vocabulary) by the words 'single' and 'by its URI', though it never names those siblings explicitly.

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 and no mention of the sibling alternatives (skos_search, skos_get_vocabulary). The phrase 'by its URI' weakly implies the caller must already hold a concept URI, but the choice between this tool and skos_search or skos_get_vocabulary is left entirely to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the result is a hierarchically organized concept scheme, but says nothing about remote-fetch failure modes, caching, or how the 'flat' option changes output beyond what the schema states.

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 zero filler; the action and return shape are front-loaded and nothing is repeated.

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

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

With no output schema, the description usefully sketches the return value (concept scheme with hierarchical concepts), which is the key missing piece. Only the absence of sibling-routing guidance keeps it from being fully complete.

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 all three parameters (uri, flat, language) are already fully documented in the schema. The description adds no syntax, format, or defaulting detail beyond 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+resource ('Fetch and parse a SKOS vocabulary from its URI') and clarifies the return shape ('concept scheme with all concepts organized hierarchically'). It does not explicitly differentiate itself from siblings like skos_get_concept or skos_search, 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?

There is no guidance on when to use this tool versus skos_get_concept (single concept) or skos_search (concept search). The description only restates what the tool does; the agent must infer selection criteria from tool names alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description's only added behavioral content is the default field set, which is really parameter information; it says nothing about matching semantics (exact/prefix/substring), result ordering, or how limit interacts with paging. Adequate but thin for a search 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 short sentences, purpose front-loaded, no filler or redundancy in phrasing. It is efficient, though the second sentence spends its budget restating schema defaults rather than adding new 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?

With fully documented parameters, complete read-only annotations, and no output schema to explain, the definition is close to self-sufficient for invocation. The residual gap is search behavior (match type, ordering, multi-language handling), which an agent would have to discover empirically.

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%, including the fields enum, limit bounds, and language example, so the baseline is 3. The description's default-fields sentence duplicates what the schema already states verbatim, adding no new meaning about how query matching or language fallback works.

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 for concepts in a SKOS vocabulary." An agent can tell it apart from the get-style siblings (skos_get_concept, skos_get_vocabulary) by inference, but the description never names those alternatives explicitly, so sibling differentiation is left implicit.

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 second sentence describes default search behavior rather than when to choose this tool over skos_get_concept or skos_get_vocabulary. There is no stated context, prerequisite, or exclusion (e.g., "use this when you only have a label fragment; use skos_get_concept when you already have a URI").

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