Search Freeport Nostr events by kind, tag & geohash radius (rides, services, reputation).
Scored across 6 tools
Each tool has a clearly distinct purpose: create_post for publishing intents, get_event for fetching events, profile for user metadata, query_raw for arbitrary queries, search_intents for finding intents, and search_reputation for reputation data. There is no overlap or ambiguity.
Tools follow a pattern of 'prefix_verb_noun' (e.g., get_event, create_post, search_intents), but nostr_profile deviates by using a noun alone. The convention is mostly consistent across the set, with only a minor inconsistency.
With 6 tools, the server is well-scoped for its purpose. It covers both generic Nostr operations and Freeport-specific functionalities without being too sparse or overwhelming.
The server covers core Freeport operations (publishing intents, searching intents, fetching reputation) and essential Nostr lookups. A minor gap is the inability to filter intents by author, but the generic query_raw tool can partially compensate.
Publish a Freeport intent — an OFFER (side "offer": driver/provider/seller) or a REQUEST (side "request": rider/buyer). Provide EITHER a secretKey (nsec or hex — the server builds, signs and publishes; use a DEDICATED agent key, never a personal one — it is used once and never stored) OR a pre-signed event (you sign locally; nothing secret reaches the server). Strict rate limits apply. Returns the published event id + addressable d.
| Name | Required | Description | Default |
|---|---|---|---|
| d | No | Stable id to republish/replace an existing post; defaults to random. | |
| side | No | offer = provider/seller/driver; request = buyer/rider. | |
| event | No | A complete, signed Nostr event (kind 32101/32102). Use instead of secretKey to keep keys off the server. | |
| title | No | ||
| market | No | Market key, e.g. "rideshare" or "service". | |
| relays | No | ||
| schema | No | Payload schema, e.g. "rideshare/1" or "service/1". | |
| topics | No | Topic `t` tags (area/category), e.g. ["vn_hanoi","vn_hanoi_ridesharing"]. | |
| window | No | ||
| payload | No | Intent payload (from/to/location, payment, etc.) per the freeport://protocol resource. | |
| geohashes | No | Geohashes for location-scoped discovery. Each is expanded into all its prefixes (precision 1-6) so radius searches at any precision match. | |
| secretKey | No | nsec or 64-hex private key. Used transiently to sign; never stored. Omit if passing a pre-signed `event`. | |
| expiresInMinutes | No | How long the post stays live (default 720). Max 30 days. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses transient key usage, return value (event id + d), and rate limits. It implies overwrite behavior via 'd' parameter but does not explicitly state side effects or authorization needs. Adequate but not fully exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph with clear flow: purpose, auth methods, rate limits, return. All sentences add value. Could be slightly shorter but efficient.
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 parameters, nested objects, and no output schema, the description is moderately complete. It explains return format and rate limits, but does not cover error handling, detailed behavior of window/payload, or idempotency. Adequate but leaves some gaps.
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 77%, so baseline is 3. The description adds value beyond schema by explaining purpose of secretKey, event, side, and d. It clarifies the side enum and transient nature of secretKey. Some parameters (window, payload) are only in schema, but overall helpful.
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 clearly states the tool publishes a Freeport intent, distinguishing between OFFER and REQUEST. It uses specific verbs ('Publish') and resource ('Freeport intent'), and is distinct from sibling tools which are read/search operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use secretKey vs pre-signed event, mentions strict rate limits, and advises using dedicated keys. However, it lacks explicit when-not-to-use or alternative tool comparisons, though siblings are all read-oriented so no direct competition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one or more events by id. Returns the raw signed events.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | ||
| relays | No | Override the relay set for this call (ws/wss URLs, max 10). Defaults to the server relays. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral disclosure. It states that the tool returns 'raw signed events,' which is useful, but it does not disclose whether the tool is read-only, how it handles missing IDs, or any relay dependency beyond the schema. Additional context (e.g., that it fetches from Nostr relays) would improve transparency.
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 a single 7-word sentence with no redundant information. It is concise and front-loaded, containing only essential action and result.
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?
Given the tool's two parameters and lack of annotations/output schema, the description provides the core function but lacks usage guidance, parameter details, and behavioral context. It is adequate but incomplete for optimal agent decision-making, especially compared to sibling tools.
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 50% (only the 'relays' parameter has a description in the schema). The description adds minimal context by mentioning 'by id,' implying the 'ids' parameter, but does not explain the required format (e.g., hex event IDs) or constraints. This partially compensates for the missing schema description but not fully.
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 uses a specific verb 'Fetch' and clearly identifies the resource 'events by id'. It distinguishes from sibling tools like nostr_query_raw and nostr_profile, which serve different purposes (raw query vs fetching by known IDs).
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 guidance is provided on when to use this tool versus alternatives such as nostr_query_raw or nostr_search_intents. The description does not mention when this is the appropriate choice, e.g., when you have specific event IDs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch NIP-01 profile metadata (kind 0) for one or more pubkeys — name, about, picture, nip05, lud16, etc. Optionally include each author's most recent notes (kind 1). General-purpose: works for any Nostr user, not just Freeport.
| Name | Required | Description | Default |
|---|---|---|---|
| relays | No | Override the relay set for this call (ws/wss URLs, max 10). Defaults to the server relays. | |
| pubkeys | Yes | Hex pubkeys to fetch profiles for. | |
| recentNotes | No | If >0, also fetch up to this many recent text notes (kind 1) per pubkey. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the event kinds (0 and optionally 1) and data fields, but does not mention error handling, relay behavior, or authentication needs. Adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently front-load the main purpose and scope, with no wasted words 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 fetch tool, the description covers the primary functionality and return values, but lacks details on error states or relay handling. Output schema is not provided, but return fields are listed.
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%. Description adds context by elaborating that pubkeys are for profile metadata and that recentNotes fetches kind 1 text notes, slightly increasing meaning beyond the schema descriptions.
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?
Description clearly states the tool fetches NIP-01 profile metadata (kind 0) for one or more pubkeys, including specific fields. It distinguishes from siblings by mentioning it's general-purpose and not limited to Freeport.
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?
Description implies usage for any Nostr user but does not provide explicit guidance on when to use this tool versus alternatives like nostr_get_event or nostr_query_raw. No when-not or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Escape hatch: run an arbitrary NIP-01 filter (kinds/authors/ids/tags/since/until/limit). Use the typed tools above when they fit. Returns raw signed events.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | ||
| tags | No | Tag filters, e.g. {"t":["vn_hanoi"],"g":["w3gv"]}. Keys are single tag letters. | |
| kinds | No | ||
| limit | No | ||
| since | No | ||
| until | No | ||
| relays | No | Override the relay set for this call (ws/wss URLs, max 10). Defaults to the server relays. | |
| authors | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden. It mentions 'escape hatch' implying raw, low-level access, and specifies return of raw signed events. However, it does not disclose limitations like rate limits, performance implications, or error handling, which would be expected for a low-level 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?
The description is two sentences long, front-loaded with the key concept 'escape hatch', and every word adds value. There is no redundant 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?
Given the complexity (8 params, nested objects, no output schema), the description is too minimal. It does not explain the relay override, tag format, or the structure of returned events, leaving significant gaps for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25%, and the description does not add parameter-level details beyond listing filter fields in the summary. For a tool with 8 parameters including complex objects (tags, relays), the description provides insufficient semantic guidance.
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 clearly states the tool runs arbitrary NIP-01 filters and returns raw signed events. The phrase 'escape hatch' distinguishes it from sibling typed tools, which are likely more restrictive.
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 explicitly advises to use typed tools when they fit, providing clear context for when not to use this tool. However, it does not elaborate on when exactly to use this escape hatch, e.g., for advanced queries or debugging.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Freeport ride/service/product intents (offers & requests). Filter by side, category/area topic tags, and an optional geographic radius. Results are decoded, expiry-filtered, and sorted nearest-first when a point is given.
| Name | Required | Description | Default |
|---|---|---|---|
| near | No | Filter & sort by distance from this point. | |
| side | No | offer = drivers/providers/sellers; request = riders/buyers; any = both | any |
| limit | No | ||
| since | No | Only events created at/after this unix-seconds time. | |
| until | No | Only events created at/before this unix-seconds time. | |
| relays | No | Override the relay set for this call (ws/wss URLs, max 10). Defaults to the server relays. | |
| topics | No | Topic `t` tags to require (category/subcategory/area keys, e.g. "vn_hanoi", "ridesharing"). | |
| includeExpired | No | ||
| relaySideGeohash | No | Also narrow at the relay via a #g cover of the radius. Only effective if posts carry geohash-prefix tags; off by default. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explicitly states that results are 'decoded, expiry-filtered, and sorted nearest-first when a point is given', which gives agents useful behavioral context beyond the schema. It does not mention side effects or permissions, but for a search tool the disclosure is sufficient.
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?
At only two sentences, the description is extremely concise. The first sentence clearly states the purpose, and the second adds key operational details (decoded, expiry-filtered, sorted). There is no wasted text, and the structure is front-loaded and easy to parse.
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?
Given 9 parameters, a nested object, and no output schema, the description covers the main filtering dimensions (side, topics, radius) and result processing (decoded, filtered, sorted). However, it omits mentions of other parameters like 'relaySideGeohash', 'includeExpired', 'limit', 'since', 'until', and 'relays', which could leave agents uncertain about their existence or relevance. It is adequate but not fully comprehensive.
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 78%, so the baseline is 3. The description provides a high-level summary ('Filter by side, category/area topic tags, and an optional geographic radius') but does not add significant new meaning beyond what the schema already conveys. Each parameter is well-documented in the schema, so the description adds minimal value.
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 clearly states the tool searches 'Freeport ride/service/product intents (offers & requests)', which is a specific resource distinct from sibling tools like nostr_query_raw and nostr_search_reputation. The verb 'Search' and resource are unambiguous, and the mention of filtering by side, topics, and geographic radius further clarifies its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching intents in Freeport, but it does not explicitly compare with alternatives like nostr_search_reputation or nostr_query_raw. It provides no guidance on when to use this tool over others, leaving the AI agent to infer from the name and context. A brief distinction from siblings would improve clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch reputation signals for a pubkey: karma ratings (kind 32103) it received and deal receipts (kind 32104). Returns proven-deal count (both receipt halves present) and a karma summary. Note: scores are subjective and un-weighted here; do not treat as Sybil-proof.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| pubkey | Yes | Subject pubkey (hex) to look up reputation for. | |
| relays | No | Override the relay set for this call (ws/wss URLs, max 10). Defaults to the server relays. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden. It discloses the subjective nature of scores and the requirement for both receipt halves for proven-deal count. However, it does not explain how karma ratings are aggregated or mention any side effects or dependencies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundancy. The main action is front-loaded, and the important caveat is succinctly placed at the end. Every word contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description omits details on output format (no schema provided), pagination via 'limit', and relay selection behavior. It explains the core data but lacks completeness for a tool with no output schema and 3 parameters.
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 input schema covers 2 of 3 parameters with descriptions (pubkey, relays). The description adds no extra meaning for these parameters and does not clarify the undocumented 'limit' parameter (e.g., pagination behavior). It fails to compensate for the 67% schema coverage.
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 clearly states the verb 'Fetch' and the resource 'reputation signals for a pubkey', specifying the relevant event kinds (32103 and 32104) and the outputs (proven-deal count, karma summary). It distinguishes this tool from siblings like nostr_search_intents by focusing on reputation data.
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 offers no guidance on when to use this tool versus alternatives like nostr_search_intents or nostr_query_raw. The only additional note is a caution about subjectivity, but no comparative context or preconditions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
freeport_create_post1 field changedInput schema / properties / geohashes / descriptionPrevious value: -"Geohash tags for location-scoped discovery."New value: +"Geohashes for location-scoped discovery. Each is expanded into all its prefixes (precision 1-6) so radius searches at any precision match."freeport_create_postnostr_get_eventnostr_profilenostr_query_rawnostr_search_intentsnostr_search_reputationSearch bounded public Bluesky keywords, handles, mentions, and hashtags.
Search ATProto writing, annotations, identity, agents, and forum posts. 12 read-only tools.
Search 2b2t locations, groups, highways, renders, Archive warps, and WDL metadata.
Agent registry with Nostr identity, reputation, escrow, observability, and Lightning payments.
Add one secure layer between your agents and this server.