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

With no annotations, the description carries the full behavioral burden, yet it says nothing beyond the definition of the result set — not that it is a read-only query, whether it is exhaustive or paginated, or how 'accepted' vs. proposed links are treated. This is the main weakness for a tool an agent may call blindly.

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?

A single short sentence with no filler, which is proportionate to a zero-parameter tool. It is a noun phrase rather than a front-loaded verb clause, which slightly weakens the opening.

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 presence of an output schema removes the need to document return values, and no parameters need explaining, so the remaining gap is behavioral and usage context. For a simple read tool that gap is tolerable but still leaves the agent guessing about scope and semantics of 'accepted'.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. An empty schema leaves no ambiguity for the agent to resolve.

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 fragment 'Requirements with no accepted link yet' identifies the resource set returned but supplies no verb, so it is unclear whether the tool lists gaps, counts them, or computes a coverage metric. It is distinguishable from siblings like get_requirement and propose_link by subject matter, but the operation itself is only implied.

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?

There is no statement of when to call this versus alternatives such as trace_matrix or get_requirement, and no preconditions are given. Usage can only be inferred from the phrase 'no accepted link yet'.

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

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

No annotations exist, so the description carries the full disclosure burden and does little. It does convey one useful trait — that the response includes the other flows of the parent use case, not just the requested item — but says nothing about behavior for a missing/invalid ID, permissions, or output shape.

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?

A single short sentence with no wasted words, but it is a fragment that omits the action verb; brevity here reads as under-specification rather than discipline.

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 simple single-parameter lookup with no annotations and no output schema, the description leaves too much implicit: it doesn't state retrieval semantics, error behavior, or how it relates to the other knowledge-graph tools. Only the return-scope hint is genuinely useful.

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?

Only one parameter with 0% schema description coverage, so the description must compensate. The 'UC10S1' example does clarify the expected ID format, which the schema does not, but the description never states what the parameter means or whether it accepts other ID schemes.

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 is a noun phrase rather than a verb+resource statement, but it does identify the resource (a requirement / use-case flow) and its scope (the other flows of the same use case). The 'UC10S1' example anchors the ID style. It fails to say the tool retrieves by ID and does not differentiate itself from siblings like related_classes or trace_matrix.

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?

No indication of when to call this versus the sibling tools (search_code, read_class, related_classes, trace_matrix, coverage_gaps). Usage has to be inferred entirely from the name.

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

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

With no annotations, the description must carry the full behavioral burden; it does disclose the key trait that the result is a pending proposal routed for review rather than an immediate write to the trace matrix. It says nothing about permissions, duplicate/pending-link handling, idempotency, or what the call returns, so the write path is only partly characterized.

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 tight sentences with no filler; the core action comes first and the queue-vs-matrix distinction follows immediately. Every clause earns its place.

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 3-required-param mutation tool with no annotations, no output schema, and zero schema descriptions, the description captures the most important workflow semantics (pending review) but leaves parameter intent and edge-case behavior undocumented. Adequate to route the call, not sufficient to call it confidently.

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 0%, so the description is responsible for parameter meaning, yet it explains none of the three required fields explicitly. 'class implements a requirement' lets an agent infer class_name and requirement_id, but 'reason' is completely unaddressed and no format or constraint hints are given.

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?

States a specific verb (propose) and resource (a link between a class and a requirement), and explicitly contrasts the outcome with the sibling trace_matrix. An agent can distinguish it from trace_matrix and related_classes without opening any schema.

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 clause 'goes to the review queue, not the trace matrix' tells the agent when this tool is the right choice versus trace_matrix. It stops short of stating preconditions (e.g., use only when the link is unverified or does not yet exist) or exclusions for other siblings.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states what data is returned but omits any information about read-only nature, permissions, error handling, or other behavioral traits.

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 and front-loaded, containing no wasted words. However, it is a noun phrase rather than a structured explanation, which slightly limits its helpfulness.

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?

An output schema exists, so the description's enumeration of return contents is largely redundant. Meanwhile, it fails to address parameter semantics or usage alternatives, leaving clear gaps for an agent trying to invoke the tool correctly.

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?

The single required parameter 'name' has 0% schema description coverage, and the description does not explain its format or meaning beyond implying a class name. It adds minimal value over the bare schema field.

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 identifies the resource (a class) and the specific information returned: package, comment, and method signatures. It is distinguishable from most siblings by content, but it does not explicitly differentiate itself from related_classes or search_code.

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 offers no explicit guidance on when to use this tool versus alternatives such as related_classes or search_code. The intended use (retrieving class details) is only implied by the listed return contents.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It usefully states that results come from the call graph and covers both outgoing and incoming usage, but it does not clarify limitations such as direct versus transitive relationships or freshness.

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 with no wasted text. It is appropriately brief for a simple query tool, though the verb "Project" is slightly awkward.

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?

An output schema exists, so return values need not be explained in the description. However, for a one-parameter tool with no schema descriptions and no annotations, the definition omits essential parameter formatting and usage guidance.

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?

The sole parameter is undocumented in the schema at 0% coverage, and the description only implies it is a class name. It does not specify whether the name should be fully qualified, simple, case-sensitive, or otherwise formatted.

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 gives a specific relationship query: it returns the classes a given class uses and the classes that use it, sourced from the call graph. It is clear what the tool does, but it does not differentiate itself from siblings such as read_class or trace_matrix.

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?

There is no explicit guidance on when to use this tool versus alternatives like read_class, search_code, or trace_matrix. The intended use for dependency or reverse-usage analysis is only implied.

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

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

With no annotations at all, the description carries the full behavioral burden and does little: it never says whether matching is keyword or semantic, whether results are ranked or capped, or what happens with zero matches. It only discloses the shape of each result (names, packages, purposes), which the output schema already covers.

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 short sentences with zero filler, and the capability statement is front-loaded ahead of the return-value note. Nothing here could be cut without losing information.

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 output schema means return values needn't be re-explained, which the description correctly avoids over-elaborating. However, for a search tool with one entirely undocumented parameter and several overlapping siblings, the description leaves search semantics and sibling selection under-specified.

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% for the single required `query` parameter, so the description must compensate. The phrase "by what they do" usefully implies the query is a natural-language description of behavior rather than a class name, but it gives no guidance on phrasing, expected length, or matching strictness.

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?

"Find classes by what they do" states a specific verb (find) and resource (classes) and adds a scoping qualifier — behavior-based rather than name-based lookup. It never names the obvious alternative, read_class, so an agent must infer the split from the sibling list rather than from the description.

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?

There is no explicit when-to-use statement and no alternative is named. A reader can infer that this tool is for discovery when the class name is unknown, but that inference is not stated, and nothing says when to prefer read_class or related_classes instead.

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

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

With no annotations, the description carries the full disclosure burden, yet it never states that this is a read-only, side-effect-free operation, nor what 'reviewed and accepted' status filtering entails. It adds only a thin filter semantic (accepted links only) and says nothing about scope or freshness of the matrix.

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?

A single compact sentence with no filler, front-loading the key qualifier 'Reviewed and accepted'. It is terse to the point of being cryptic, but nothing is wasted.

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?

An output schema exists, so return values need not be explained, and zero parameters keep the call surface trivial. However, the description leaves the action and scope of the matrix unstated, which is a real gap for an agent deciding between this and coverage_gaps.

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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to clarify beyond what an empty schema already implies.

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 phrase 'Reviewed and accepted links: requirement id -> classes' conveys the data the tool exposes (a requirement-to-class mapping) but contains no verb or explicit action, so an agent must infer that this is a lookup/retrieval. The 'reviewed and accepted' qualifier does distinguish it from propose_link, but only indirectly.

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?

There is no explicit when-to-use guidance, no mention of alternatives like coverage_gaps or get_requirement, and no stated prerequisites. The only implied usage cue is that it returns accepted rather than proposed links.

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