company_sourcing

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

With no annotations, the description carries the full burden, and it discloses meaningful behavior: each gap is priced, a cheapest feasible route is selected, and the result updates a skill capacity ledger and generates requisitions for recurring shortfalls. It also notes that a taxonomy and match report are used if supplied, otherwise built. It does not mention permissions or reversibility, but the core behavioral consequences are conveyed.

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 one long, dense run-on sentence with multiple embedded clauses and semicolons. It packs meaningful information but in a structure that is difficult to scan or parse. This is not concise; it sacrifices clarity for comprehensiveness.

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 complex tool with 7 parameters, 0% schema description coverage, and no annotations, the description is not complete enough. It omits parameter semantics, prerequisites, and clear usage boundaries. The output schema reduces the need to describe return values, but an agent still lacks essential guidance on how to construct a valid call.

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 for undocumented parameters. It references 'payload jobs and profiles', 'taxonomy', and 'sealed match report', which likely relate to payload_json or bundle_json, but it never maps these concepts to the actual parameter names. project_id and bundle_json are required yet receive no explanation, leaving an agent to guess their structure and role.

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 clear verb and resource: 'Plan the labour for every skill gap.' It then enumerates the distinct sourcing routes (assign, upskill, contract, hire), which helps distinguish this tool from single-route siblings like company_hiring or company_contractors. However, the dense run-on phrasing and unexplained jargon make the purpose harder to parse than it should be.

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 implies the tool is for planning labour across skill gaps and selecting the cheapest feasible make-before-buy route. It does not name alternatives or state when not to use it, and no exclusions are provided. The use case is inferable but not explicitly contrasted with sibling tools.

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