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

Annotations already indicate this is a non-read-only, non-idempotent mutation. The description adds that it is a write operation adding a segment to the tenant, which is consistent but not deeply revealing; it does not mention permissions, duplicate handling, or side effects beyond creation.

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 short sentences with no filler; the primary action is stated first, followed by a useful scoping note about being a write operation on the tenant. Every sentence earns its place.

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 schema fully covers parameters and annotations cover the safety profile, but there is no output schema and the description does not state what a successful call returns (e.g., created audience ID). It also omits any usage guidance relative to sibling tools, leaving some context for the agent to infer.

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 100%, so every parameter is already documented. The description's phrase 'set of attribute rules' maps to the rules parameter but adds no semantics beyond the schema, so the baseline 3 is appropriate.

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 ('Creates'), a concrete resource ('audience/segment'), and the input mechanism ('from a set of attribute rules'). It clearly distinguishes this creation tool from sibling read tools like sitecore_personalize_audience_list and sitecore_personalize_audience_get.

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 states what the tool does but does not explicitly say when to choose it over alternatives or mention any preconditions. Usage is implied by the create verb and sibling names, but no explicit routing or exclusions are provided.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It correctly communicates that this is a read-only retrieval operation and specifies what is retrieved, which is useful. However, it does not mention error behavior, authentication requirements, rate limits, or what happens when the audience ID is not found, leaving a partial gap for a no-annotation 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 a single, front-loaded sentence with no filler. It states the action, the object, the scope, and the lookup key in one concise line. Every word contributes, and there is no redundant restatement of the tool name or title.

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 one-parameter get tool with no output schema, the description is nearly complete: it tells the agent what will be retrieved and how to identify the target. The only minor gap is the absence of any statement about error responses or missing IDs, but given the low complexity and direct read-only nature of the operation, the description is adequately 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 input schema provides 100% coverage: audienceId is already described as 'The unique identifier of the audience/segment.' The description reinforces this by saying 'by ID' but does not add new semantic detail beyond the schema. Baseline 3 is appropriate because the schema already handles parameter documentation.

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 states a specific verb ('Retrieves'), a precise resource ('the definition and membership rules of a single audience/segment'), and the selection key ('by ID'). This clearly differentiates it from sibling tools like audience_list, which would return multiple audiences, and audience_create, which creates rather than retrieves.

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 makes the usage context implicit but clear: use this tool when you have an audienceId and need the detailed definition and membership rules for that single segment. It does not explicitly name alternatives or exclusion criteria, but the 'single audience/segment by ID' wording is sufficient to steer an agent away from list and create siblings.

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

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

No annotations are provided, so the description carries the behavioral burden. It uses the read-only verb 'Lists' and mentions pagination support, which is helpful, but it does not disclose response shape, ordering, or any authorization/scope constraints.

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 filler. The core action is front-loaded ('Lists audiences') and the pagination note is directly relevant to the tool's parameters.

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-only list operation with a fully documented two-parameter schema, the description is largely sufficient. It names the returned entity and mentions pagination, though an explicit return-shape statement would be stronger since no output schema exists.

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 100%, so the baseline is 3. The phrase 'Supports pagination' characterizes limit and offset as pagination controls, but adds no meaning beyond what the schema already documents.

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 and resource: 'Lists audiences (segments)' configured in Sitecore Personalize/CDP. This clearly distinguishes it from sibling list tools like flow_list and experience_list, and from audience_get and audience_create.

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 intended use is implied by the purpose: an agent should call this when it needs a collection of audiences. However, the description does not explicitly mention alternatives such as audience_get for single-audience retrieval, leaving routing to inference.

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

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

No annotations are provided, so the description carries the behavioral transparency burden. 'Retrieves' clearly indicates a non-mutating read operation, and specifying 'metadata and schema information' gives some sense of the returned content. However, it does not disclose authentication requirements, error behavior, or any side-effect-free guarantees beyond the verb itself.

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 sentence with no filler, and the essential facts—what it retrieves and how the dataset is identified—are front-loaded. 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?

For a tool with one required, well-documented parameter and no output schema, the description covers the core behavior and return content sufficiently. It is slightly incomplete in that it does not route the agent to the sibling list tool when the ID is unknown, but that is a minor gap for such a simple operation.

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 sole parameter is already fully documented in the schema with type, minLength, and a clear description. The description's 'by ID' adds no new meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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 names a specific verb ('retrieves'), a specific resource ('single dataset'), and the access path ('by ID'), which clearly distinguishes it from the sibling dataset_list operation. It also tells the agent the exact kind of data returned: metadata and schema information.

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: use this when you need metadata/schema for one dataset and already have its ID. It does not explicitly mention when not to use it or point to dataset_list for enumeration, so the guidance is inferred rather than explicit.

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

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

With no annotations, the description carries the full burden of behavioral disclosure, yet it only conveys a read operation via the verb 'Lists'. It does not mention pagination behavior, effect of limit/offset on iteration, ordering, rate limits, or response shape. Not misleading, 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?

A single 13-word sentence with zero filler. The verb is front-loaded, the resource is specific, and the parenthetical examples add real value without bloating the text. Every word earns its place.

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 list tool with two optional, fully documented parameters, the description covers the core 'what' adequately. However, with no output schema and no usage guidance, an agent is left guessing about pagination iteration and return structure. Meets the minimum viable bar but has clear 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 description coverage is 100%, with limit and offset fully documented including ranges and defaults. Per the baseline rule for high coverage, a 3 is appropriate; the description adds no parameter-specific meaning beyond what the schema already provides.

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 names a specific verb ('Lists'), a concrete resource ('datasets'), and a scope boundary ('available in the tenant'), then clarifies with examples ('e.g. product catalogs, custom reference data'). This distinguishes it cleanly from sibling list tools (flow_list, experience_list, audience_list) which target different resources, and from dataset_get which targets a single dataset.

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 provides zero guidance on when to reach for this tool versus its 16 siblings. It never mentions that for a single dataset one should use dataset_get, nor does it offer any condition or context that would route an agent here. Given the large sibling set, this is a notable gap.

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

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

Annotations already carry the core behavioral traits: readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description states 'This is a write operation,' which is consistent with readOnlyHint=false but adds little beyond the annotation. It does add useful context that events feed real-time and batch decisioning, but omits side effects like duplicate-event behavior or downstream triggers.

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 tightly written and front-loads the core action with examples. The second sentence ('This is a write operation.') is somewhat redundant given readOnlyHint=false, but it is short and does not significantly bloat the description.

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 schema and annotations cover parameters and safety profile reasonably well, and the description frames the tool's role. However, it does not mention response behavior, whether the operation is synchronous, or how missing guestRef might be handled, and it provides no alternative routing. For a write operation with no idempotency, a bit more context about downstream effects would improve completeness.

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 100%, so parameter semantics are already fully documented. The tool description adds a high-level example of event types already present in the schema and provides no additional detail about individual parameters or their relationships.

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 ('ingests') with a clear resource ('behavioral event') and destination ('Sitecore CDP'), and gives concrete event type examples. It clearly differentiates this from sibling tools like flow management, audience, or guest profile operations by focusing on event ingestion for a guest.

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 the tool is used when a behavioral event needs to be sent for real-time or batch decisioning, but it provides no explicit when-to-use or when-not-to-use guidance and does not mention alternatives. The usage context is inferable but not stated directly.

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

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

No annotations are present, so the description carries the behavioral burden. 'Retrieves' makes clear this is a read-only operation and the subtype constraint is disclosed. However, it does not mention return format, error behavior, or any special effects for missing refs — acceptable for a simple read, but not fully transparent.

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, front-loaded with the primary action and resource, then a concise equivalence note. Every sentence earns its place and there is no redundant phrasing.

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 single-resource read with one required parameter, the description covers what, how to identify the resource, and how it relates to a sibling. The absence of an output schema is offset by the 'Retrieves a single experience' phrasing, though more detail on the returned object would make it fully 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?

Schema coverage is 100% with flowRef documented as 'The unique reference (ref) of the flow definition.' The description adds value by clarifying that this ref should refer specifically to a flow of subtype EXPERIENCE, and that it behaves like flow_get. This enrichment goes beyond the basic schema text.

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 'Retrieves' and a concrete resource: 'a single experience (flow definition with subtype EXPERIENCE) by its ref.' It also explicitly names the sibling equivalent, sitecore_personalize_flow_get, which helps distinguish it from list/execute tools despite being an alias.

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?

It clearly states the tool is equivalent to sitecore_personalize_flow_get and frames it as 'a named convenience for experience-specific workflows,' giving an agent the context to choose it when working specifically with experiences. It does not explicitly list when-not-to-use scenarios, but the equivalence statement covers the main routing need.

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

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

No annotations are provided, so the description carries the behavioral transparency burden. It communicates that this is a list operation and mentions offset/limit pagination, but pagination is already fully described in the schema, and it leaves implicit that the operation is read-only with no side effects.

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 short sentences with no filler. It front-loads the core purpose and relationship to flow_list, then mentions pagination, so every sentence earns its place.

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 tool with only two optional parameters, this is adequate for basic invocation, but no output schema and no annotations mean the description should say more about return shape or safety characteristics. 'Equivalent to flow_list' provides some transferable meaning, but the description is not fully self-contained.

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 100%, so the schema already defines limit and offset with clear meaning and defaults. The description adds no parameter-level detail beyond restating that pagination is supported, which is already captured in the schema.

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 ('Lists') and identifies the exact resource ('experiences (flow definitions with subtype EXPERIENCE) configured in Sitecore Personalize'). It also distinguishes the tool from sibling sitecore_personalize_flow_list by stating it is equivalent to that flow list with subtype='EXPERIENCE' pre-applied.

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 clearly positions this tool as the experience-specific variant of sitecore_personalize_flow_list, making it easy to infer when to choose it. However, it does not explicitly state when not to use it or name alternatives for other flow subtypes beyond the implied equivalence.

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

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

Annotations indicate the operation is not read-only and not idempotent, and the description reinforces this by saying it 'triggers' execution. However, it does not disclose potential side effects, such as whether executing a flow writes events or updates guest state, which would be valuable for an execution tool beyond the annotations.

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, tightly constructed sentence that front-loads the primary action and resource. It includes the key identifier, the guest constraint, and the return value, with no filler or repetition.

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 covers the core input (friendlyId), the guest identification rule, the execution nature, and the expected output ('flow's decision output'). Since there is no output schema, this is a reasonable level of completeness, though it could mention what happens if no guest identifier is supplied.

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 100%, so the schema already fully documents all parameters. The description repeats the 'exactly one of browserId, email, or identifiers' constraint and references friendlyId, but adds no new parameter-level guidance beyond the schema.

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 a specific verb ('Triggers real-time decisioning execution'), a resource ('published flow'), and the required identifier ('friendlyId'). It also names the guest-identification constraint and the return value, making it sharply distinct from sibling tools like flow_list, flow_get, and flow_set_status.

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 clearly establishes this tool is for executing flows, not listing, retrieving, or changing status. It gives the execution context ('real-time decisioning') and the interactive API equivalent, but it does not explicitly state when to use it over alternatives or provide exclusions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It accurately conveys this is a read-only retrieval operation returning a full definition, not a mutation or execution. It does not detail error cases or response format, but for a simple get-by-ref tool, the behavioral trait is sufficiently clear.

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, well-structured sentence that front-loads the primary action and resource, and includes the key scoping detail ('single flow', 'by its ref') without any filler or repetition.

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 tool with one simple required parameter and no output schema, the description covers the essential context: what is retrieved, its scope, and how to identify it. It could add a note about what 'full definition' includes or error behavior when the ref is invalid, but this is not a significant gap for a straightforward getter.

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 already documents flowRef with a clear description and minLength constraint, giving 100% schema description coverage. The description adds little beyond what the schema provides, only restating that lookup is by ref. This matches the baseline of 3 for high 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 uses a specific verb ('Retrieves'), identifies the resource ('full definition of a single flow'), and specifies the lookup key ('by its ref'). It clearly distinguishes this from listing flows or modifying flow status, so an agent can tell it apart from sibling tools without opening schemas.

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 clearly implies the tool is used when the agent has a flow ref and needs the complete definition of one flow, as opposed to listing flows or changing status. It does not explicitly name alternatives or exclusion criteria, but the 'single flow' and 'by its ref' phrasing provides adequate contextual guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adequately communicates that the operation is a read-only list and surfaces key behaviors like subtype filtering and offset/limit pagination. However, it does not describe the response format, default behavior when subtype is omitted, or any potential error conditions.

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 three short, purposeful sentences with no filler. It front-loads the core listing purpose, then adds filtering and pagination details, all of which earn their place.

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 optional-parameter list operation, the description combined with the complete schema is largely sufficient for an agent to invoke correctly. The only notable gaps are the lack of a described return structure and the absence of explicit guidance on how this tool relates to the sibling experience_list tool.

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?

All three parameters are fully documented in the schema, including defaults, ranges, and enum meanings, so the schema covers the heavy lifting. The description reinforces that subtype distinguishes experiment vs experience, but this largely repeats the schema's own parameter description rather than adding substantial new meaning.

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 the specific verb 'Lists' and a clear resource 'flow definitions', and further clarifies that these include experiments and experiences. The subtype filter explanation ('EXPERIMENT' vs 'EXPERIENCE') helps distinguish this tool's scope from related experience-focused tools, making its purpose unambiguous.

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 provides clear practical guidance on filtering by subtype to distinguish A/B tests from experiences and mentions pagination for larger result sets. However, it does not explicitly explain when to choose this tool over siblings like flow_get or experience_list, so it lacks explicit exclusions or alternatives.

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

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

The description goes beyond the annotations by explaining the internal mechanism: it reads the current flow definition and writes it back with the new status, and notes that updates are a full replace. It also flags production impact, which is especially useful for a write operation. Annotations already indicate non-readOnly and non-destructive, and the description adds valuable behavioral context.

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, each earning its place: the action, the reason/mechanism, and the impact. It is compact without sacrificing necessary context and frontloads the core purpose.

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 two-parameter mutation tool with no output schema, the description is complete. It explains how the operation works, why this endpoint exists, and warns about production impact. The agent has all needed information to select and invoke the tool 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?

The schema already covers both parameters with clear descriptions, including the enum guidance for status. The description largely restates the schema's examples rather than adding new parameter-level insight. With 100% schema description coverage, the baseline of 3 is appropriate.

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 states a specific action ('Changes a flow definition's status') with concrete examples ('PRODUCTION'/'LIVE' to publish, 'PAUSED' to pause), which clearly distinguishes it from sibling read/execute tools. The verb and resource are unambiguous and not a mere restatement of the tool name.

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?

It clearly communicates when to use this tool: to publish or pause a flow when there is no dedicated publish endpoint. However, it does not explicitly name an alternative or state when not to use it, though the phrase about the missing endpoint and full-replace mechanism provides strong contextual guidance.

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

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

Beyond the annotations, the description adds meaningful behavioral context: the operation is irreversible, permanently deletes associated data, and is unverified against Sitecore's official docs. It also warns the agent to confirm behavior with curl/Postman before relying on it, which is valuable operational 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 compact and well-structured: the core action is front-loaded, followed by the destructive consequence and a practical verification warning. Every sentence adds meaningful information without 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 single-parameter destructive operation, the description covers the action, consequences, typical use case, and reliability caveat. No output schema exists, but none is needed for this type of operation, and the guidance is sufficient for correct invocation.

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 already fully documents the only parameter, guestRef, with a clear description. Since schema coverage is 100%, the tool description does not need to add parameter-level details, and the baseline 3 applies.

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 states a specific verb ('Permanently deletes') and a specific resource ('guest profile and its associated data from Sitecore CDP'). It clearly distinguishes this tool from the read/search/upsert sibling tools by emphasizing the destructive nature of the operation.

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 usage context by noting it is 'typically used for privacy/right-to-be-forgotten requests' and warns that the endpoint is unverified. It does not explicitly name alternatives or when-not-to-use conditions, but no close non-destructive alternative exists among siblings.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It communicates a read-only, single-record lookup and identifies the profile as the output, but it does not mention behavior for missing guest references, authorization requirements, or response structure.

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, focused sentence with no fluff or repetition. The core action and identifier method are front-loaded, making it easy for an agent to parse quickly.

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 get-by-reference tool with one well-documented parameter, the description is mostly adequate. However, with no output schema or annotations, it would benefit from noting what fields the profile returns or how not-found cases are handled.

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 already fully describes the only parameter, guestRef, including its uniqueness and role as an identifier. The description adds little beyond the schema's own parameter documentation, so a baseline score of 3 is appropriate.

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 a specific verb ('Retrieves'), resource ('guest (visitor/contact) profile'), and lookup method ('by guest reference'). It is distinguishable from sibling tools like guest_search because it emphasizes a single profile retrieved by exact reference, though it does not explicitly name or contrast any sibling.

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 the tool should be used when you already have a guestRef and need a single guest profile. However, it does not explicitly state when to prefer guest_search or guest_upsert instead, or provide any exclusion criteria.

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

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

With no annotations, the description carries the transparency burden and does add useful behavior: pagination support and an explicit warning that the endpoint is unverified and should be confirmed with curl/Postman. However, it omits other behavioral context such as authentication requirements, error behavior, and what happens when no parameters are supplied.

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 short sentences with the core action front-loaded and the important caveat placed at the end. Nothing is wasted, and the unverified note earns its place without bloating the description.

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?

There is no output schema and no annotations, so the description must cover return shape, auth, and edge behavior, but it only covers pagination and the verification caveat. Notably, all three parameters are optional yet the description never clarifies what an empty call would return, which is a real completeness gap for an unverified endpoint.

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 100%, so the schema fully documents email, limit, and offset, including formats, bounds, and defaults. The description adds no parameter-level detail, so the baseline 3 applies — neither compensating nor detracting.

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 states a clear verb and resource ('Searches for guest profiles by email') and adds pagination, so an agent understands the core operation. It doesn't explicitly contrast with sibling guest_get or guest_upsert, but 'search by email' is a meaningfully distinct operation among the guest-family tools.

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?

There is no guidance about when to prefer this over guest_get, when not to use it, or what prerequisites exist. The use case is only implied by the verb 'searches'; the unverified-endpoint note is a caution, not a selection directive.

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

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

The description clearly discloses that the call REPLACES the entire extension group and deletes any existing key not included. This directly contradicts the annotation destructiveHint: false, which suggests the operation is not destructive. This is a significant annotation contradiction.

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 compact, front-loads the core behavior, and every sentence earns its place. The warning about unverified URL path shape is important and included without unnecessary elaboration.

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 covers the key mechanics, group selection, and a critical production caveat, but it omits return value/response behavior and provides no guidance on expected output. With no output schema present, this leaves a notable gap for an agent invoking the tool.

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 100%, and the schema already describes guestRef, attributes, and extensionGroup including the replacement behavior. The tool description adds little parameter-specific meaning beyond what the schema provides, so a baseline of 3 is appropriate.

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 sets arbitrary custom key/value attributes on a guest via a specific mechanism, and names the fixed extension groups. This distinguishes it well from sibling tools like guest_get, guest_upsert, and guest_delete.

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 some usage context (e.g., use a consistent extension group per source system) and explains the replacement behavior, but it does not explicitly state when to prefer this tool over alternatives or when not to use it. The usage guidance is implied rather than explicit.

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

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

Annotations already establish read-write, non-destructive, idempotent behavior. The description adds the POST/PUT mechanism boundary and the scope of fields it touches, which is useful behavioral context beyond the annotations. It does not clarify whether PUT is a full replacement or a partial update, but annotations plus the explicit method switch still make behavior reasonably transparent.

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 filler; the action and condition are front-loaded, and the boundary with the data-extension sibling is stated compactly. Every sentence earns its place.

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 17-parameter, zero-required tool with no output schema, the description covers the essential selection and invocation facts: what kind of fields it accepts, how to choose between create and update, and which sibling to use for custom attributes. It could add whether PUT replaces or merges existing values and what happens on a new guest when fields are omitted, but those are localized gaps rather than missing selection-level context.

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 41%, so the description carries part of the load. It groups the fields into base guest object categories (name, contact info, address, etc.), which helps with the many undocumented fields, and it reinforces the guestRef create/update toggle. It does not explain ambiguous fields like 'title' or state update semantics, and the schema still has to do most of the individual field work.

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?

States a specific verb (creates/updates), the resource (CDP guest profile), the HTTP methods (POST/PUT), and the triggering condition (guestRef present). It also distinguishes itself from the data-extension sibling, so an agent can tell which tool handles base fields versus custom attributes.

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?

Explicitly says to use this tool for base guest object fields and names the alternative (sitecore_personalize_guest_set_data_extension) for arbitrary custom key/value attributes. It also encodes the create-v-supdate decision rule based on guestRef, which is direct when-to-use guidance.

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