yardstick_built_in_agents_enable_previewPreview enabling a built-in agent; returns the approval-required envelope stating exactly what starts happening (and what is never sent without you) plus binding fields. Side-effect free.
| Name | Required | Description | Default |
|---|---|---|---|
| request_id | No | ||
| idempotency_key | No | ||
| built_in_agent_id | Yes |
Changes observed during successful MCP inspections.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint false, idempotentHint true, destructiveHint false), the description explicitly says 'Side-effect free' and details what the response will contain: the approval-required envelope, what starts happening, what is never sent without you, and binding fields. This gives substantial behavioral context that annotations do not provide.
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 lean sentence that front-loads the action ('Preview enabling...') and packs in key behavioral and return-value information. There is no redundant or filler content.
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 excels at explaining purpose and output, but with zero parameter documentation and no mention of idempotency or request_id despite the idempotentHint annotation, it leaves notable gaps. An agent could call the tool but would be unsure how to properly supply parameters, so it is only minimally adequate.
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 0%, and the description provides no explanation of the parameters (built_in_agent_id, request_id, idempotency_key). The agent is left without any semantic guidance on which IDs to use or how idempotency works, making this a major gap.
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 'Preview enabling a built-in agent' – a specific verb and resource – and clarifies 'nothing changed yet', making it distinct from the sibling enable_bind tool. The 'Side-effect free' note reinforces that this is a preview, not an actual mutation.
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 indicates this is a preview action and is safe to invoke without side effects, implying it should be used before the actual enable operation. However, it does not explicitly name the alternative bind tool or give an explicit when-not-to-use condition, so it falls short of full explicitness.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.