pullsheet-diagnostics

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

With no annotations provided, the description carries full disclosure burden. It compensates well by detailing the return structure: 'structured diagnosis with confidence level, reasoning chain, potential causes, and repair steps.' This is valuable behavioral context given the absence of an output schema, though it omits error handling or rate limit details.

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 appropriately sized at four sentences with logical flow: purpose → inputs → outputs → attribution. It is front-loaded with actionable information. The final sentence about PullSheet is slightly extraneous branding for an AI agent but does not significantly detract from utility.

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 lack of output schema and annotations, the description adequately compensates by explaining what the tool returns. With only two well-documented parameters (both required), the context provided is sufficient for invocation, though explicit error scenarios would improve completeness further.

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 schema has 100% description coverage, establishing a baseline of 3. The description adds 'in plain English' for the symptom parameter, which aligns with but doesn't significantly expand upon the schema's existing 'Plain-English description' field. No additional semantic context is provided for equipment_type beyond the schema's enum values.

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 'Diagnose[s] an elevator, escalator, or vertical transportation equipment issue,' using a specific verb (diagnose) and resource. It importantly clarifies that the tool handles multiple equipment types beyond just elevators (which the name suggests), distinguishing its scope appropriately.

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 prerequisites by stating 'Provide equipment type and describe the symptom,' giving clear context on required inputs. However, it lacks explicit when-to-use guidance, exclusion criteria, or comparison to the sibling tool get_common_symptoms (e.g., not stating to use this when seeking a diagnosis versus retrieving reference symptoms).

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 provided, the description carries the full burden of behavioral disclosure. It adds valuable context by citing the data source 'PullSheet,' but fails to disclose whether the operation is read-only (implied by 'Get' but not stated), rate limits, caching behavior, or what the response structure looks like.

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 appropriately compact with two clear sentences followed by data attribution. The purpose is front-loaded in the first sentence, and the second sentence provides usage context without redundancy. The PullSheet citation adds provenance value without cluttering the operational 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?

Given the tool has only two simple enum parameters (no nested objects) but lacks an output schema, the description adequately covers inputs but omits any description of the return format or structure. For a retrieval tool with no output schema, mentioning that it returns a list of symptom objects with severity levels would improve completeness.

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 100%, with both 'equipment_type' and 'severity_filter' fully documented in the schema including enum values. The description references 'specific type of vertical transportation equipment' aligning with the equipment_type parameter, but adds no additional semantic context (examples, validation rules) beyond what the schema already provides, warranting the baseline score.

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 retrieves 'a list of common issues and symptoms' (specific verb + resource) for 'vertical transportation equipment.' It implicitly distinguishes from sibling 'diagnose_elevator_issue' by emphasizing 'browsing' and 'helping a technician identify what they're seeing' rather than performing diagnosis, though it could explicitly contrast the two workflows.

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 provides context for when to use the tool ('browsing known problems,' 'helping a technician identify what they're seeing'), but lacks explicit guidance on when NOT to use it or direct comparison to the sibling diagnostic tool. The usage is implied but not rigorously bounded.

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