tool_publish_csdn

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

With no annotations, the description carries the full burden and does: it discloses the rate limit (2/day, 30 min apart) only on direct publish, that drafts are not rate-limited, that skip_rate_limit risks a ban, that UI selectors may break and a screenshot is saved on failure, and the exact fields it fills in the editor. It also warns about anti-automation flags and CSDN's terms.

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?

Front-loaded with the core behavior and default, then warnings, then Args, then Returns — well structured and scannable. It is longer than strictly necessary (the terms/anti-automation remarks partly repeat the rate-limit paragraph), so not a perfect 5.

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 an 8-parameter, annotation-free, no-output-schema mutation tool, the description closes every gap: defaults, rate-limit policy, auth prerequisite, failure modes, and the return dict shape are all documented. An agent has everything needed to invoke it correctly and interpret the result.

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 0%, so the description must compensate and does — every one of the 8 parameters is explained with meaning, source/default, and effect (tags/category/visibility 'override' front-matter, visibility only meaningful when as_draft=False, headless=False to watch the action, skip_rate_limit scoped to as_draft=False). This is more than the schema alone could convey.

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?

Opens with a specific verb+resource ('Send a local draft to CSDN') and names the mechanism (browser automation, Plan A). It distinguishes itself from siblings by pointing at write_blog as the source of the file and csdn_login as a precondition, so the agent can place it in the pipeline without reading other 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?

Explicitly states the default behavior (as_draft=True saves without publishing, review manually) versus the alternative (as_draft=False publishes publicly and returns a URL), and states the prerequisite 'call csdn_login first'. It even covers the failure branch: expired session returns needs_login=True so you re-run csdn_login.

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