Announce a Capability#

A capability is a typed unit of work a node can do. An announcement places its descriptor and provider properties into the distributed fold. Callers with the required discovery authority can then find it. Invocation is a separate decision.

Two things you can announce#

Tags describe what a node is — gpu, region:eu-west, a model it hosts, an accelerator it has. Nothing is callable; you are populating a placement index so somebody can find a machine that fits.

Tools describe what a node can do — a named, schema'd operation an agent can invoke. A tool is the thing an LLM's tool-call resolves to.

Most agent code wants tools. Most placement code wants tags. They travel in the same capability set and are announced by the same call.

Serving a tool and announcing a tool are different acts#

Most bindings expose these as separate operations:

1. Serving registers a handler on an RPC surface, so that a call addressed to that tool name reaches your function.
2. Announcing puts the tool's descriptor into your capability set, so that peers folding your announcement learn the tool exists.

Do the first without the second and you have a working tool nobody can find: discover returns nothing, invoke fails to route, and neither error mentions announcing. In Rust the two are fused — registering a tool inserts it into the node's tool registry and the next announce carries it. In TypeScript, Python and Go they are not, and each fragment below shows the explicit merge step its binding needs.

The RPC handle#

The tool API does not hang off the node. It hangs off a typed RPC surface constructed over the node — serve, call, list and watch are all operations on that surface.

Rust is the exception, and it is the reason this is worth spelling out: in Rust the mesh node is that surface, so the tool methods are node methods. Documentation written from Rust first tends to project that shape onto the other three, where it is wrong. Take the constructor from your own fragment.

Announcement mechanics#

Announcements expire. The default TTL is five minutes. Re-announce before it elapses or peers garbage-collect your entry and you quietly stop being discoverable.

Re-announcing is cheap. The mesh diffs against your last announced set, so a steady-state re-announce costs tens of bytes rather than a full rebroadcast. There is no reason to hand-roll change detection.

Announcements travel multi-hop, bounded by a hop count, so a peer several hops away can fold your capability without ever having connected to you directly.

Announcing to nobody succeeds. If the node has no connected, started peers, the announce call returns cleanly and reaches no one. If discovery remains empty, confirm the node has joined a peer before changing the capability filter. See the handshake.

Discovery and invocation have separate authority#

Announcing does not make a capability visible to every participant or open to invocation.

Visibility and invocability are separate decisions. Organization-scoped discovery can hide or encrypt a descriptor for callers outside its audience. The provider then makes the final admission decision when a caller invokes it. See Invoke and Errors.

The full tag and axis model — hardware, software, model, tool, resource-limit projections — is in Capabilities and Capability Schema.

Announce it — Rust#

The ergonomic path for a callable tool is the #[tool] attribute. It needs two things the Quickstart's install does not pull in:

cargo add net-mesh-sdk --features macros   # net_sdk::macros is opt-in
cargo add schemars@1                       # for #[derive(JsonSchema)]

macros is off by default so consumers who never write a #[tool] do not pay the proc-macro build cost, and schemars has to be a direct dependency of your crate because your types derive JsonSchema themselves. Skip either and this page's example does not compile:

error[E0432]: unresolved import `net_sdk::macros`
note: ... the item is gated behind the `macros` feature
error[E0432]: unresolved import `schemars`

use net_sdk::macros::tool;
use net_sdk::mesh::{Mesh, MeshBuilder};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
 
#[derive(JsonSchema, Deserialize, Serialize)]
struct WebSearchReq {
    /// Free-text query string.
    query: String,
}
#[derive(JsonSchema, Deserialize, Serialize)]
struct WebSearchResp {
    results: Vec<String>,
}
 
#[tool(
    description = "Search the web for relevant pages.",
    tag = "web",
    tag = "research",
    estimated_time_ms = 500
)]
async fn web_search(req: WebSearchReq) -> Result<WebSearchResp, String> {
    Ok(WebSearchResp { results: vec![format!("first hit for '{}'", req.query)] })
}

#[tool] derives the JSON Schema from JsonSchema, captures the metadata, and generates a register function named after the function: web_search_register.

Serve and announce#

let host = MeshBuilder::new("127.0.0.1:0", &PSK)?.build().await?;
 
let _handle = web_search_register(&host)?;   // registered; unregisters on drop
host.announce_capabilities(Default::default()).await?;

This is the binding where the two steps fuse. web_search_register inserts the descriptor into the node's tool registry, and announce_capabilities merges the registry into whatever set you pass — which is why Default::default() is enough here and is not enough anywhere else on this spine.

The returned handle unregisters on drop. Binding it to _handle rather than _ matters: let _ = web_search_register(&host)?; drops it immediately and deregisters the tool you just served.

Tags without a tool#

use net_sdk::capabilities::CapabilitySet;
 
let caps = CapabilitySet::new()
    .add_tag("region:eu-west")
    .add_tag("gpu");
host.announce_capabilities(caps).await?;

announce_capabilities_with(caps, ttl, sign) overrides the five-minute default and controls signing.

Verify it worked#

Verify from another peer after it folds the announcement:

// `agent` is handshaked with `host`, per the Quickstart.
let deadline = std::time::Instant::now() + std::time::Duration::from_secs(3);
while std::time::Instant::now() < deadline && agent.list_tools(None).is_empty() {
    tokio::time::sleep(std::time::Duration::from_millis(20)).await;
}
assert!(!agent.list_tools(None).is_empty(), "the announcement did not fold");

Folding is asynchronous, so the loop is the point — an immediate list_tools after announce_capabilities will usually be empty, and that is not a failure.

The full announce → list → lower → invoke loop is sdk/examples/tool_calling.rs, which runs in CI.

Next: Discover a capability.