1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
//! Tool definition types — MCP-aligned metadata.
use serde::{Deserialize, Serialize};
use crate::envelope::Envelope;
use crate::io::ToolSchema;
/// How the frontend should handle the tool result.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize)]
#[serde(rename_all = "lowercase")]
#[non_exhaustive]
pub enum ExecutionHint {
/// Tool executes a real operation; result is authoritative.
#[default]
Backend,
/// Tool only validates/extracts params; frontend drives the action.
Ui,
/// Tool executes backend AND frontend should refresh/navigate.
Hybrid,
/// Unknown hint from a newer protocol version; normalizes to Backend.
#[serde(other)]
Unknown,
}
impl Serialize for ExecutionHint {
fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
match self.effective() {
Self::Backend | Self::Unknown => serializer.serialize_str("backend"),
Self::Ui => serializer.serialize_str("ui"),
Self::Hybrid => serializer.serialize_str("hybrid"),
}
}
}
impl ExecutionHint {
/// Return the effective hint, mapping Unknown → Backend.
#[must_use]
pub const fn effective(self) -> Self {
match self {
Self::Unknown => Self::Backend,
other => other,
}
}
}
/// Optional hints about tool behavior (MCP-aligned).
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct Annotations {
/// Human-readable title.
#[serde(skip_serializing_if = "String::is_empty", default)]
pub title: String,
/// Grouping category for UI.
#[serde(skip_serializing_if = "String::is_empty", default)]
pub category: String,
/// Freeform tags for filtering.
#[serde(skip_serializing_if = "Vec::is_empty", default)]
pub tags: Vec<String>,
/// True if repeated calls produce the same result.
#[serde(skip_serializing_if = "Option::is_none", default)]
pub idempotent_hint: Option<bool>,
/// Tells the frontend how to handle the tool result.
#[serde(default)]
pub execution_hint: ExecutionHint,
}
/// Describes a tool — MCP-aligned metadata.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Definition {
/// Unique tool identifier.
pub name: String,
/// Human-readable description.
pub description: String,
/// JSON Schema for the tool's input parameters.
pub input_schema: ToolSchema,
/// Optional JSON Schema for the tool's output.
#[serde(skip_serializing_if = "Option::is_none")]
pub output_schema: Option<ToolSchema>,
/// Behavioral hints that are orthogonal to the executable permission envelope.
#[serde(default)]
pub annotations: Annotations,
/// Executable permission envelope — the single source of truth for what the tool may do at runtime.
/// It carries scopes, network/filesystem/ subprocess rules, safety classification,
/// sensitive-invocation predicates, and data-classification hints. Defaults deny network, filesystem,
/// and subprocess access.
#[serde(default)]
pub envelope: Envelope,
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn unknown_execution_hint_effectively_serializes_as_backend() {
let hint: ExecutionHint = serde_json::from_str(r#""future""#).expect("unknown maps");
assert_eq!(hint.effective(), ExecutionHint::Backend);
assert_eq!(
serde_json::to_value(hint).expect("hint serialises"),
serde_json::json!("backend")
);
}
}