find_quantity_kind

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only states that it searches, implying a read-only operation, but does not disclose potential side effects, permissions, case sensitivity of the substring, whether it returns all matches or just one, or any pagination behavior. For a search tool, the absence of these details leaves the agent uncertain about the exact behavior.

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 a single, front-loaded sentence that states the verb, resource, and parameter purpose with zero redundancy. Every word earns its place, and the structure is efficient and easy to parse.

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 the tool's simplicity (one parameter) and the presence of an output schema, the description covers the basic intent but omits details that would improve completeness, such as the scope of the search (entire model vs. current package), result ordering, or behavior on no matches. These are relevant for an agent deciding how to use the tool alongside siblings like find_by_name and search, making the description adequate but not exhaustive.

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?

With schema description coverage at 0%, the description must compensate. It adds the critical context that the 'name' parameter is matched as a substring, which goes beyond the bare schema. However, it does not specify case sensitivity, whether matching is case-insensitive, or any wildcard behavior, leaving partial ambiguity. The description adds some meaning but not enough to fully define the parameter's semantics.

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 'Search', a specific resource 'the model for SysML QuantityKind-stereotyped elements', and a filtering criterion 'by name substring'. This clearly differentiates it from siblings like find_by_name (which likely searches by name without stereotype restriction) and find_by_type (which searches by type), making the tool's purpose unambiguous.

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 this tool (when searching for QuantityKind-stereotyped elements by name), but it does not explicitly mention alternatives or exclusions. It doesn't contrast with find_by_type, find_unit, or search, leaving the agent to infer the selection criteria based on the stereotype emphasis. No explicit when-not-to-use guidance is provided.

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