run_sdk_project_workflow

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 discloses an important safety trait: 'hosted connector writes fail closed,' and it implies that live operations should not be run through this tool. However, it does not explain side effects, whether non-connector writes are allowed, what happens on validation failure, or any authorization requirements beyond the vague 'authorized governed execution surface.' Some behavioral context is present, but key behaviors remain opaque.

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 short and front-loaded with the core action, followed by constraints and routing advice. Every sentence contributes a distinct piece of information. The heavy use of unexplained jargon like 'compact Backbone and sovereign progressive profiles' reduces clarity, but the structure itself is appropriately concise for an MCP tool 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?

This is a complex seven-parameter tool with no annotations and no parameter documentation, so the description should provide substantial context; it does not. It fails to explain the required project_spec and workflow_key, the meaning of approval_refs, the effect of preview_only, or how connector_account_refs interacts with the fail-closed behavior. The output schema exists, but the description still leaves too many essential operational details unexplained for an agent to invoke the tool confidently.

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%, so the description must compensate for the seven undocumented parameters, but it does not clearly explain inputs, run_ref, project_spec, workflow_key, approval_refs, or connector_account_refs. The mention of 'preview' and 'hosted connector writes' hints at preview_only and connector_account_refs, but these are not explicit. The description adds almost no direct parameter-level meaning beyond what the raw schema field names imply.

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 opens with a specific verb and resource: 'Run an SDK project workflow locally.' This clearly identifies the tool's core action and distinguishes it from broader workflow tools like run_workflow or trigger_workflow, though the exact meaning of 'SDK project workflow' is not expanded. The 'locally' qualifier adds useful scope, but the description does not explicitly differentiate among the many workflow-related siblings.

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 indicates that preview and validation modes are appropriate on certain profiles, and warns against routing live operations through this tool ('Route intended live operations through an authorized governed execution surface'). This gives a clear when-to-use and when-not-to-use signal, even if the alternative surface is not explicitly named. The guidance is somewhat jargon-heavy but sufficient to steer an agent away from live production use.

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