mesh_find_record

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

No annotations are provided, so the description must carry the burden of behavioral disclosure. It discloses the realm constraint (no realm parameter, protocol-internal) and the default host behavior, which are key behavioral traits. It doesn't mention error cases (e.g., record not found) or rate limits, but for a simple fetch operation, the provided context is sufficient. The default host is explicitly stated, which is helpful.

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 sentences with zero fluff. The primary action and key constraint are front-loaded, and the default host is at the end as a minor detail. Every sentence adds critical information. No redundancy with the 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 simple read-by-key tool with only 2 parameters incl. one optional, and no output schema, the description covers the essential semantics: what the key is, the realm constraint, and default host. It doesn't describe return format (e.g., the DHT record structure), but since there's no output schema, the description could have clarified what 'record' means, though it's minor. Given the tool's simplicity, this is nearly 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?

The schema description coverage is 100%, so the schema already documents both parameters well. The description adds context for key_hex by clarifying it's specifically the storage key (not the advertiser/signer key), which is valuable beyond the schema. It also adds host default behavior, but that's already in the schema. Given full schema coverage, a baseline of 3 is appropriate; the added key distinction justifies not lower.

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'), the resource ('one DHT record'), the identifier ('32-byte storage key'), and the specific protocol context (DHT's all-zero realm). It distinguishes from siblings like mesh_find_records and mesh_find_records_by_type by emphasizing it fetches a single record by exact key. This is a specific and unambiguous purpose.

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 clear context for when to use this tool: when you have an exact 32-byte storage key (e.g., from ProcedureKey or prior search results). It implicitly distinguishes from search tools that return multiple records, but doesn't explicitly name them as alternatives or say when not to use this tool. Exclusions (no realm parameter) are stated, but no direct comparison to siblings like mesh_find_records.

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