campus_research_read_source_file

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial behavior beyond them: 20 MB file cap, 20-page-per-call cap, re-fetch/re-parse on every call, temporary file URL not returned, no OCR, and no automatic scientific validation. These are exactly the operational constraints an agent cannot infer from the 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?

Front-loaded with the core purpose and conditions, then constraints, then the alternative-tool routing. Dense and information-rich, though the anti-overclaiming instruction ('do not claim a complete review') and the citation-caveat sentence make it longer than strictly necessary.

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, no-output-schema tool, the description supplies the missing return-relevant context (temp URL not returned, sourceUrl is unverified) plus limits, re-fetch behavior, and the alternative-tool path. An agent has everything needed to invoke it correctly and interpret its limitations.

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 the load, and it does for the important ones: pageCount ('up to 20 pages per call'), page ranges (startPage intent), and sourceUrl ('an unverified bibliographic claim until title, authors and publication are compared with the PDF'). It is weaker on the nested source_file fields (file_id, download_url, file_name, mime_type), which are never explained, leaving a small gap.

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 precise verb+resource (read specific pages of a student-attached PDF), plus the triggering condition (publisher URL cannot be fetched by Campus). It explicitly names the sibling it is not (campus_research_index_pdf), so an agent can distinguish it from the other campus_research_* readers 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?

Gives an explicit when-to-use ('PDF explicitly attached by the student... when its publisher URL cannot be fetched') and a when-to-prefer-something-else ('If a public PDF URL is available and relevant pages are unknown or spread across chapters, prefer campus_research_index_pdf'). It also instructs how to behave on long PDFs (select page ranges, report pages read, don't claim full review).

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