skillgild_run_skill

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

With no annotations, the description carries the full burden and does well: it discloses that input is transmitted to an external AI provider, that execution may consume a free allowance or paid entitlement, and that generated output is returned. It omits failure modes, latency, and whether calls are idempotent or retryable, which matters for a billed operation.

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?

Four short sentences, front-loaded with the action and the routing rule, then the cost/external-provider disclosure, then the safety warning. Every sentence carries distinct information with no repetition of structured fields.

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?

Covers cost implications, external data transmission, and a data-handling warning, which is strong for a nested-input tool with no annotations and no output schema. The remaining gap is not pointing at how an agent discovers a skill_id or its input schema, which matters given the free-form nested object.

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%, so both parameters (skill_id, input) are already documented and the description only restates that input is JSON matching the skill's public schema. Baseline 3 applies; it adds no format examples or guidance on where to obtain a skill's public input 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?

States a specific verb and resource ('Run a SkillGild prompt_pipeline skill') plus the two identifying inputs (public ID/slug, JSON input). It also names the sibling it is not, distinguishing prompt_pipeline skills from hybrid_tools skills, so an agent can route without opening either schema.

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?

Gives an explicit routing rule: use skillgild_start_session instead for hybrid_tools skills, which is a real when-not condition. It does not mention skillgild_search_skills as the way to discover a valid skill_id, so the alternative-space is only partially covered.

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