Publish to Netrun

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

Annotations only provide idempotentHint and destructiveHint, neither of which reveals much about side effects. The description adds meaningful behavioral traits: waits for the build, returns public URL or failure reason, may return needs_secrets, auto-detects language, and implies 'put it online' is a state-changing publish action. It doesn't discuss deployment costs, overwrite behavior, or what happens to previous versions, but it discloses the core flow.

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?

Five sentences, front-loaded with the core action. Each sentence earns its place by explaining mode selection, language detection, wait behavior, return values, and the secrets callback. Minor redundancy with schema details, but it remains dense and readable.

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?

Given no output schema secret, the description must explain the return contract, and it does: public URL, failure reason, or needs_secrets. It covers the main edge case (secrets) and the update workflow關鍵. It doesn't mention rate limits, cleanup, or how to use related tools like netrun_set_secrets, but for an 8-parameter publish tool with nested objects and a retry flow, it is substantially 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 88%, so the schema already documents most parameters well, e.g. project_id ('Existing project to update. Omit to create a new one') and secrets ('Stored encrypted...'). The description adds cross-parameter logic (pass name OR project_id) and the meaning of the return value ('needs_secrets'), but it doesn't need to restate parameter formats since the schema handles them.

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?

Description uses specific verbs ('Upload a project folder and put it online') and clearly scopes the resource: creates a new project or ships a new version of an existing one. It distinguishes behavior from siblings like netrun_list_projects or netrun_status, and also distinguishes create vs update modes.

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?

Provides concrete guidance: 'pass name' for a new project, 'pass project_id' for an existing one, and a retry workflow when the tool returns needs_secrets ('ask the user... call again with secrets'). It doesn't explicitly contrast with sibling tools, but the include/exclude conditions for name vs project_id are clear.

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