list-sub-statuses

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

No annotations are provided, so the description must disclose behavioral traits on its own. It adds domain knowledge about top-level statuses but doesn't mention read-only nature, pagination behavior, response structure, or any error conditions. The schema covers parameters, but with no output schema, the description should clarify what the response contains. The lack of any behavioral disclosure beyond the basic 'List' verb leaves significant gaps.

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 extremely concise: two sentences, no fluff. It front-loads the purpose, then adds essential domain context and usage guidance. Every sentence contributes value, making it an efficient and well-structured description.

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 description omits important context for a tool with 8 parameters and no output schema. It does not mention what a sub-status entity looks like (e.g., id, name), whether filtering or pagination is relevant (though schema covers this), or any rate limits. The top-level status explanation is helpful but insufficient for an agent to know what to expect from the response. More behavioral and return-value context is needed.

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 88%, so the baseline is 3. The description does not add parameter-specific detail beyond what the schema already provides, but the mention of 'Use the IDs' indirectly clarifies the purpose of the returned data, which helps contextualize the tool. It does not compensate for the uncovered parameters, but those are already well-documented in the schema.

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 the tool's function: 'List matter sub-statuses.' It also distinguishes from siblings by specifying the relationship to top-level statuses ('pnc, hired, or lost') and explicitly ties it to use with create-matter / update-matter, which differentiates it from other list tools like list-stages or list-pipelines.

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 practical usage context: 'Use the IDs with create-matter / update-matter.' This tells the agent when the tool is relevant (when needing sub-status IDs for those mutations). It does not explicitly contrast with alternatives, but the context is clear enough for a list utility. No exclusions are stated, but the primary use case is conveyed.

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