build_advisor

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

With no annotations, the description carries the full burden and does disclose the key non-obvious trait: this is a long-running BACKGROUND JOB that returns {job_id} immediately and must be polled via job_status. It does not cover permissions, failure modes, or rate limits, keeping it just short of a 5.

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 and dense: pipeline, then advisor_dir path, then the async warning, then the prerequisite. Every clause carries signal, though the arrow notation and abbreviations assume shared vocabulary.

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?

There is no output schema, but the description explains the return value ({job_id}) and the polling mechanism, filling that gap well. For a 4-param tool it is only incomplete on parameter meanings, but the operational behavior an agent needs is present.

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, but it only clarifies one of four parameters (advisor_dir = advisors/{name}). The stages 'corpus → kernels → индекс' hint at run_kernels/run_index, yet neither those flags nor 'author' is given any meaning.

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+resource ('Собрать советника' / build an advisor) and enumerates the pipeline stages (manifest-gate → corpus → kernels → index), so the agent understands it is a turnkey build operation. It is clearly distinguishable from validate_manifest and the catalog/federation 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?

Explicitly prescribes the prerequisite ('Сначала validate_manifest' – run validate_manifest first) and the correct follow-up pattern ('не жди здесь' – don't wait, poll job_status). It names the alternative tool and the condition under which it is used.

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