rca_guide_ingest

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

Annotations only say readOnlyHint=false and destructiveHint=false, so the description carries the behavioral burden. It adds valuable process detail: fault codes (F-###, ERR-###) are auto-extracted for markdown, plain text is split on double newlines, the guide is immediately searchable after ingestion, plan limits apply, and the return JSON contains guide_id, section_count, symptom_count, and fault_code_count. No contradiction with annotations.

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 well-structured and front-loaded, with bulleted formats, plan limits, and return shape. Nearly every section earns its place, but the emoji decoration and the partially redundant Args block add slight noise, so it is not perfectly concise.

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 moderate complexity of a nested input and the absence of a visible output schema, the description covers comparable essentials: what formats are supported, how each is processed, what happens after ingestion, plan constraints, and return fields. It does not cover error/duplicate behavior or auth requirements, but the schema documents token and the annotations cover the safety profile.

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 nested schema already documents every field in GuideIngestInput, so the description's Args list is mostly redundant. The real added parameter value is in the format explanations: markdown auto-extracts fault codes, plain splits on double newlines, and json_dtree routes to interactive diagnostics. The Args summary omits token and client_id, which keeps this from a 5.

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 names a specific verb and resource: 'Upload and index an equipment troubleshooting guide into the knowledge base.' It also distinguishes itself from a clear sibling by saying 'Use rca_guide_ingest_pdf instead if you're starting from an actual PDF file.' An agent can tell exactly what this tool does and what it is not for.

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?

It explicitly tells the agent when to use the PDF sibling versus this tool, and it gives format-selection guidance: markdown is recommended, plain splits on double newlines, and json_dtree is for interactive diagnostics via rca_dtree_start. It also notes the guide becomes searchable via rca_guide_search, which clarifies the post-ingestion workflow.

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