auto_onboard_and_convert

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

With no annotations, the description carries the full behavioral burden, yet it never says that this writes into project_dir and run_dir, whether the operation is idempotent or resumable, what 'provider-backed' implies (network calls, credentials, cost, latency), or what happens on partial failure mid-pipeline. 'Deterministic admission' hints at a check step but not at pass/fail consequences.

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?

A single clause with no filler, so nothing is wasted, but that brevity comes from omission rather than precision; the three abstract nouns are packed without front-loading what the agent actually needs (required inputs, side effects).

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 11-parameter orchestration tool with side effects on two directories, no annotations, and no parameter documentation, one sentence is far too thin. The output schema covers return values, but nothing tells an agent how to fill required fields, what the defaults mean, or what the pipeline mutates.

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?

Eleven parameters with 0% schema description coverage means the schema provides titles only, and the description contributes nothing: source, run_dir, matching, osm_data, match_profile, svg_mode, svg_font_dirs, force_bootstrap are all undefined. This is exactly the case where the description must compensate and does not.

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 names three phases (onboarding, admission, conversion) and implies an orchestrated pipeline, which is more than a tautology. But 'deterministic admission' is unexplained jargon, and it never distinguishes itself from siblings like run_conversion, bootstrap_project, or prepare_ai_onboarding/apply_ai_onboarding, which together appear to cover the same ground.

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?

There is no statement of when to use this bundled pipeline instead of the individual onboarding/convert tools, and no prerequisites or exclusions. The only implied guidance is the conjunction 'and', which weakly suggests it does multiple steps at once.

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