vibeshooting — Егор Севастьянов

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

Annotations already declare readOnly/idempotent/non-destructive and closed-world, and the description adds real value on top: it discloses the returned statuses, the `missing` feedback field, that the result is not an order acceptance, and a privacy constraint against passing personal/confidential data.

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?

Purpose is front-loaded in the first clause, followed by invocation flow, status vocabulary, and the privacy caveat. Dense but each sentence carries distinct information, with only mild redundancy around the optional-fields workflow.

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?

With an output schema present the description needn't detail return values, yet it still explains statuses and the `missing` field. Combined with the privacy constraint and optional-field guidance, it covers what an agent needs, though it could say more about how the fit statuses should be acted on.

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 the schema already documents all eight parameters and their enums, setting the baseline at 3. The description adds only the meta-guidance that fields are optional and that only categories and counts should be supplied, not per-parameter semantics.

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 object ('Check whether a product shoot fits Egor's published routes') and enumerates those routes (remote AI, hybrid, photography, video), so an agent can distinguish it from siblings like draft_brief or find_portfolio.

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 clear invocation guidance: all fields optional, pass what the user already said, then ask about fields returned in `missing`, and clarifies this is a preliminary check rather than order acceptance. It doesn't explicitly contrast against sibling tools, but the when-to-use context is strong.

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

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

Annotations declare readOnlyHint/idempotent/non-destructive, and the description reinforces this by ruling out misreadings that its name invites: 'this tool sends, stores and books nothing' clarifies that generating a message is not sending one. It adds a privacy constraint ('Do not include names, phone numbers or other personal data') that appears nowhere in structured fields.

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?

Three sentences, front-loaded with the deliverable, then sequencing, then constraints. No filler; each sentence changes how an agent would behave.

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?

An output schema exists, so return format need not be described. Combined with the sequencing, the no-side-effects statement and the privacy rule, an agent has everything needed to call this after check_shooting_fit and present the result correctly.

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 100% with per-field descriptions and enums for category, channels, deliverable and sourceMaterial, so the schema carries parameter meaning. The description adds no field-level syntax or format guidance beyond what the schema already provides; baseline 3 applies.

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?

Names a precise verb and artifact ('Build a ready-to-send first message to Egor in his four-point brief format') and enumerates the concrete outputs (Telegram deep link, mailto link). An agent can distinguish it from siblings immediately, since the sibling check_shooting_fit is called out as the predecessor.

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?

Explicit sequencing: 'Use after check_shooting_fit' states the prerequisite, and the follow-up instruction to surface the `missing` points before sending gives a concrete post-call action. It also clarifies the division of labor — the user reviews and sends, the tool does not.

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

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world, non-destructive), and the description adds real behavior beyond that: Russian word-form and marketplace-term normalization, AND semantics ('all words must match'), and the fallback path that returns category cases with fallback=true. It does not discuss result size or how fallback results differ beyond the flag.

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 tight sentences with no filler; the core purpose is front-loaded and each following sentence adds actionable behavior. It is dense but every clause carries information.

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?

With a full output schema, 100% parameter coverage, and safety annotations, the description only needs to cover matching logic and edge cases, which it does: fallback behavior, AND-matching, and how to interpret an empty result. Nothing an agent needs to call or interpret this tool is missing.

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% with enums and defaults already documented, so the baseline is 3. The description earns an increment by explaining the matching semantics of 'query' (language forms, marketplace terms, all-words-must-match) and the conditional behavior tied to 'category', which the schema alone does not 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?

States a specific verb and resource: finding documented product-shooting cases filtered by category, method and words. The scope is clear and distinct from a fit-checking or brief-drafting tool, but it never names or contrasts with the sibling tools (e.g. check_shooting_fit), so the agent gets no explicit routing signal.

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?

Usage context is implied (search the portfolio of documented cases) rather than stated, and no alternative tool is named for when this search fails or when a fit check is the real need. The note that a miss does not prove lack of experience is decision-relevant, but it is interpretive rather than a when-to-use rule.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely useful context beyond them: prices are deliberately withheld and surfaced in a first reply, and no booking or sending occurs. It does not discuss the returned payload, but the output schema exists to cover that.

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?

The content scope is front-loaded in the first sentence, with the two short follow-ups adding the pricing caveat and the no-side-effects guarantee. Slightly long single sentence, but every clause earns its place.

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 a single-enum-parameter read tool with a full output schema and complete annotations, the description covers what is returned per topic and the key non-behaviors. Nothing critical to correct invocation is missing.

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 100% and the enum values are already documented, including the note that 'contact' returns the brief and working terms. The description largely restates the same topic list ('exact FAQ answers', 'contact with brief requirements and working terms'), so it adds little beyond the schema — the baseline 3.

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: 'Read published facts about Egor Sevastyanov' with the four content areas (profile, services, FAQ, contact). This clearly separates it from sibling tools like draft_brief and check_shooting_fit, though no sibling is named explicitly, which is why it stops short of 5.

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 useful when-to-use context by enumerating what each topic yields, and adds a when-not clause ('Prices are not published... Nothing is booked or sent'), steering agents away from using it for pricing or bookings. It does not name the alternative tool for those needs, so it is not a full 5.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior. The description adds genuinely non-derived traits: the answer is a dated summary with a source link and may be stale because 'rules change', which is important operational context that the annotations cannot convey.

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?

Three sentences, front-loaded with what the tool returns, followed by the staleness caveat and audience note. Dense and mostly waste-free, though the trailing audience sentence is the least essential part.

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?

An output schema exists, so return-format detail is unnecessary, and annotations carry the safety profile. The description supplies scope, content coverage, provenance, and a staleness warning, leaving nothing an agent needs before calling it.

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 100% and the single enum parameter already documents 'omit to get all three'. The description names the three marketplaces but adds no filtering semantics, formatting, or edge-case behavior beyond the schema, so it sits at the baseline.

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 resource (official photo requirements for Wildberries, Ozon, Yandex Market product cards) and enumerates exactly what it covers: formats, resolution, aspect ratio, file size, image count, main-image rules, and moderation failure causes. An agent can distinguish this from siblings like find_portfolio or draft_brief without opening any 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 clear applicable context ('useful for any seller, not only Egor's clients') and a concrete usage instruction ('tell the user to check the source before upload'). It does not name alternatives or state when not to use it, so it stops short of a 5.

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