intake_request

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It says the tool 'persists' data, implying a write operation, but doesn't disclose whether it's idempotent, whether it can be called multiple times for the same assignment, what happens on duplicate requests, or what the response contains. The mention of 'categorize' hints at classification behavior but doesn't explain how classification is used or what happens if it's absent.

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 with no filler. The core action is front-loaded, and the classification guidance is a useful addition. It earns its place, though it could be slightly more informative without becoming verbose.

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?

The tool has 5 parameters, no annotations, no schema descriptions, and an output schema that isn't explained. The description is too thin to guide an agent on how to construct a correct call, especially for optional parameters like family_id and source_ref. It also doesn't clarify the relationship to sibling tools like create_family or create_project, which is important given the large sibling set.

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 the schema's lack of parameter documentation. It only clarifies the purpose of 'classification' ('IntakeGov should pass its classification when available'), leaving family_id, source_ref, and classification_source unexplained. With 5 parameters and zero schema descriptions, this is a significant gap.

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 states a specific verb ('Persist and categorize') and resource ('a new assignment'), which clearly distinguishes it from execution-oriented siblings like start_slice or resolve. It doesn't explicitly name a sibling, but the phrase 'before execution' positions it as an intake/pre-execution step, which is enough to differentiate it from the many other tools.

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 when to use it ('before execution') and mentions that IntakeGov should pass its classification when available, which gives some context about a specific caller. However, it doesn't explicitly state when not to use it or name alternatives like create_project or create_family, leaving the agent to infer the boundary between intake and project/family creation.

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