Struct ToolDecl 

pub struct ToolDecl {
    pub name: String,
    pub description: Option<String>,
    pub sql: Option<String>,
    pub path: Option<String>,
    pub method: Option<String>,
    pub base_url: Option<String>,
    pub script: Option<String>,
    pub ui_resource_uri: Option<String>,
    pub parameters: Vec<ParamDecl>,
    pub annotations: Option<AnnotationsDecl>,
}

Single [[tools]] entry — a declaratively-defined tool surface.

Fields

name: String

Tool name (required for production via ServerConfig::validate).

description: Option<String>

Human-readable tool description.

sql: Option<String>

SQL template (uses :param placeholders bound by ParamDecl).

path: Option<String>

HTTP request path for a single-call OpenAPI/REST tool (D-01), e.g. "/Line/Mode/tube/Status". Concatenated onto the backend base_url (or this tool’s Self::base_url override). Additive per REF-01 — None for SQL / script tools.

method: Option<String>

HTTP method for a single-call tool ("GET", "POST", …). Pairs with Self::path (D-01). Additive; None for SQL / script tools.

base_url: Option<String>

Per-tool backend base-URL override. When absent a single-call tool inherits [backend].base_url. Additive; None for SQL / script tools.

script: Option<String>

JavaScript body for a script tool (D-01) — a code-mode snippet that orchestrates multiple backend calls and binds [[tools.parameters]] to args. When set, this entry is a script tool (Self::is_script_tool). Additive; None for SQL / single-call tools.

ui_resource_uri: Option<String>

Optional UI-resource URI for structuredContent widgets.

parameters: Vec<ParamDecl>

[[tools.parameters]] — declared input parameters.

annotations: Option<AnnotationsDecl>

[tools.annotations] — MCP toolAnnotations.

Implementations

impl ToolDecl

pub fn is_script_tool(&self) -> bool

Whether this [[tools]] entry is a script tool (D-01 detection rule).

The detection rule is: script.is_some() ⇒ script tool; otherwise a path + method pair ⇒ single-call HTTP tool; otherwise (a sql field) ⇒ SQL tool. Plan 03/05 synthesizers branch on this method so the rule lives in exactly one place. Mutual-exclusivity is enforced at ServerConfig::validate (an entry mixing kinds is rejected, not silently resolved by precedence).

Examples

use pmcp_server_toolkit::config::ToolDecl;

let script = ToolDecl { script: Some("await api.get('/x')".into()), ..Default::default() };
assert!(script.is_script_tool());

let single = ToolDecl {
    path: Some("/Line/Mode/tube/Status".into()),
    method: Some("GET".into()),
    ..Default::default()
};
assert!(!single.is_script_tool());

pub fn param_position(&self, param_name: &str) -> ParamPosition

Where param_name sits for the purposes of the D3 default length cap (Phase 128).

Derivation

• The name appears as a {name} segment of Self::path -> ParamPosition::Path.
• Else Self::method carries a request body (method_carries_request_body: POST, PUT, PATCH) -> ParamPosition::Body.
• Else there IS a method -> ParamPosition::Query. A method with no request body has nowhere but the URL to carry a non-path input, OPTIONS included.
• Else (no method at all) -> ParamPosition::Body: a SQL named bind or a script-tool argument.

Coupling with tools.rs::build_operation — structural, not documentary

Both of this function’s splits agree with build_operation because both read the same helper, not because a comment says so:

• the PATH arm and build_operation’s path_param_names both read path_placeholder_names;
• the QUERY/BODY arms and build_operation’s ParameterLocation assignment both read method_carries_request_body, which is also the sole source of Operation::has_request_body.

The second agreement is Phase 128 CR-02/CR-03, and it replaced a documented “deliberate divergence” that did not survive measurement. build_operation used to mark every non-path declared parameter ParameterLocation::Query regardless of method while this function answered Body for a mutating tool — justified on the grounds that the two questions (“where does the value TRAVEL” versus “where is LENGTH dangerous”) are different. They are, but the answers were both wrong: the value travelled in the query string, so the D3 cap was withheld from a genuine request-line input on the stated grounds that it was a payload field, and build_body — which collected only args absent from operation.parameters — sent no payload at all.

D-05 is still honoured, and now BY the routing rather than despite it: a Body position means the value really is a JSON payload field, and default_cap_applies emits no default maxLength for it. The escape for a long Query value remains an explicit per-parameter max_length.

Examples

use pmcp_server_toolkit::config::{ParamPosition, ToolDecl};

let search = ToolDecl {
    path: Some("/lines/{line_id}/status".into()),
    method: Some("GET".into()),
    ..Default::default()
};
assert_eq!(search.param_position("line_id"), ParamPosition::Path);
assert_eq!(search.param_position("detail"), ParamPosition::Query);

let comment = ToolDecl {
    path: Some("/issues/{id}/comments".into()),
    method: Some("POST".into()),
    ..Default::default()
};
assert_eq!(comment.param_position("id"), ParamPosition::Path);
// Free text on a mutating method is NOT capped — D-05.
assert_eq!(comment.param_position("body_text"), ParamPosition::Body);

let sql = ToolDecl { sql: Some("SELECT 1".into()), ..Default::default() };
assert_eq!(sql.param_position("anything"), ParamPosition::Body);

Trait Implementations

impl Clone for ToolDecl

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ToolDecl

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ToolDecl

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for ToolDecl

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for ToolDecl

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for ToolDecl

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for ToolDecl