build_submission_kit

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

With no annotations, the description carries the burden and does well: it discloses merge precedence ('cached scan profile with fields you pass (yours win)'), input validation behavior (placeholders like XXXX, 20XX, 'your address' are rejected and never saved), a filesystem side effect (saves .md + .json), and one return key (needs_review). It omits whether existing files are overwritten, where files are written, and what happens if no cached profile exists.

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?

About 70 words, front-loaded with the artifact and purpose, then precedence, then validation, then return value. Nearly every clause carries information; the only mild inefficiency is the abbreviated 'Saves .md + .json' without stating where.

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 15-parameter, no-annotation, no-output-schema tool that writes files, the description covers the workflow and the critical validation/precedence behavior, but leaves the majority of parameters unexplained and only names one of presumably several return fields. Adequate to call correctly, not 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 description coverage is 0% across 15 parameters, so the description must compensate and largely does not. It explains the precedence rule for passed fields and implies name/address/phone/description are the core ones, but never clarifies the save flag's default-on file-writing behavior, the socials/services array vs null semantics, or fields like category, founded, and country.

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 opens with a specific verb and artifact: 'Build one consistent Name/Address/Phone + descriptions kit for directory/citation sign-ups.' That is clearly distinct from siblings like scan_site (which produces the cached profile) and generate_schema (which it explicitly says reuses the kit). It stops short of a full sibling differentiation statement, but the artifact it produces is unambiguous.

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 is implied rather than stated: you build the kit before directory/citation sign-ups and fix 'needs_review' items before submitting, and generate_schema reuses the output. There is no explicit 'do not use when' or a named alternative for the case where no cached scan profile exists.

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