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

Description explicitly states 'does not contact suppliers' and that 'a human operator must approve every outbound recipient, message, and artifact scope.' These are critical behavioral disclosures that go beyond the provided annotations (which are absent). It also implies side effects like locking the revision and creating request lines, making the mutation behavior clear.

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?

Two sentences: first states the action and outcome, second states an important behavioral boundary. Front-loaded with the main verb and outcome, then a critical caveat. No fluff or redundant phrases.

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 annotations and no output schema, the description adds safety and scope context but lacks specifics like parameter behaviors (e.g., need_by format, substitutions_allowed implications), the meaning of 'validated project revision', or how returned candidates are structured. With 10 parameters and 18% schema description coverage, it should clarify which parameters affect behavior, especially the items array vs. auto-derived BOM lines. The description is adequate for a high-level purpose but incomplete for nuance.

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 only 18%, so the description must compensate. It surfaces the key parameter semantics: 'create normalized request lines', 'return supplier candidates', and the critical constraint of human approval on recipients/messages. While not exhaustive, it adds meaningful context beyond the schema (e.g., that items is optional and 'sources the current BOM'). The description also clarifies that the tool is about the sourcing package, not just generic searching.

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 clearly states what the tool does: lock a validated project revision, create sourcing lines, and return supplier candidates. It uses specific verbs ('Lock', 'create', 'return') tied to the resource ('immutable sourcing package'), and the qualifier 'validated project revision' differentiates it from siblings like submit_sourcing_request.

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 does not mention when to use this tool versus alternatives such as submit_sourcing_request or revise_supplier_quote. It also fails to state prerequisites like 'project must be validated' or whether it should be called before/after other tools. The only implicit guidance is that it creates a package and returns candidates, which is insufficient.

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