campus_research_index_status

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

Adds substantial behavioral context beyond the read-only/idempotent annotations: without analysisId the ledger is cumulative and cannot prove what a given answer read, indexedPages is extraction coverage only, and indexes may be lost on restart or another relay instance. This is exactly the kind of operational caveat an agent needs.

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?

Front-loads the purpose, then gives the critical analysisId guidance, then caveats. Every sentence carries useful information, though the description is dense and introduces several concepts in a short space.

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 read-only status tool with no output schema and 0% schema descriptions, the description is largely complete: it covers what is checked, the key optional parameter, and important index volatility. The only gap is not explicitly defining documentId's expected source or uniqueness.

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%, so the description must carry parameter meaning. It thoroughly explains analysisId: where to get it, why to pass it, and what happens without it. documentId is only implied as the indexed document identifier, leaving minor room for improvement.

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 and resource: check extraction progress, outline, OCR gaps, and SHA-256 for an indexed document. It names analysisId from index_pdf and distinguishes this status/ledger tool from the index creation sibling.

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?

Gives clear contextual guidance: pass analysisId from index_pdf to get readPages and verifiedEvidence, and explains the consequence of omitting it. It does not explicitly compare against audit_indexed_pdf or search_index, but the intended usage context is clear.

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