submit_drawing_extraction

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

With no annotations, the description does useful work by explaining that Kiln Business checks requirements against the selected machine and material, flags review items, and prepares quote recommendations. However, it omits key mutation behavior: what happens when save is true or false, whether the submission is persisted, whether it is idempotent, and what errors or responses to expect.

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 description is short and front-loaded with the core action, then adds the downstream verification context. The upgrade link is promotional but relevant to the Kiln Business gate, so there is little wasted text.

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?

Given no output schema, no annotations, a nested extraction object, and only 33% schema coverage, the description is not complete enough. It explains the business verification step but leaves the extraction shape, persistence behavior, and expected result undocumented.

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 only 33%, and the description mentions none of the three parameters. It does not explain what intake_id refers to, what fields the nested extraction object must contain, or what save=true controls, so it fails to compensate for the sparse schema documentation.

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 first sentence states a specific verb, resource, and goal: submit a structured extraction of a drawing for verification. It is clear what the tool does, though it does not explicitly distinguish itself from related siblings such as intake_engineering_drawing or validate_design_for_requirements.

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?

The description gives only a prerequisite ("Requires Kiln Business") and no guidance on when to use this tool versus intake_engineering_drawing, analyze_design_requirements, or other verification-related siblings. It also does not explain when an agent should submit an extraction rather than run a local validation step.

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