Survey a topic across the library
shamela_survey_topicCount how much the library holds on a term and where: the exact matching-page total plus its distribution by category, Hijri century, book and author (top 15 each). Statistics only, never passages — use shamela_search(match='words') instead to retrieve and read the pages. Run it before searching to size a topic and pick scope.category_ids (map by_category names to ids with shamela_find(kind='category')). mode 'literal' (default, 6–9 ms) counts the word as written; 'morphological' counts every derived form of its root (seconds) and is often far broader. coverage_capped:true means the breakdown is a top-5,000 sample whose counts are floors; total_hits stays exact. No match = total_hits 0; EMPTY_SCOPE when scope matches no book. Example: {term:'الاستصناع', scope:{category_ids:[14,15,16,17]}}; {term:'التيمم', scope:{citable_only:true}}.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"term": "<term>"
},
"name": "shamela_survey_topic"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | 'literal' counts pages carrying the WORD as written (plus the ordinary spelling folds). 'morphological' expands it to every AlKhalil root reading and counts those — which is far broader than most callers expect: «الاستصناع» reports 393,498 pages across 7,405 books morphologically against 1,510 literally, an answer that says every shelf holds the topic. Use 'literal' to size a topic before planning retrieval; use 'morphological' to trace a ROOT through its derivations. | literal |
| term | Yes | Arabic word or root to profile (e.g. «الاستصناع»، «صبر»، «رحم»). Under mode='literal' (default) only the word as written is counted; under mode='morphological' it is matched via the AlKhalil analyzer, so all derived forms (صابر، يصبر، اصطبار…) are counted, not just the literal string. | |
| scope | No | Restrict the profile to specific books, authors, categories, or a Hijri date range. Use shamela_find(kind='category') / shamela_find(kind='name') to find IDs. Omit to profile the whole library installed on this server. | |
| response_format | No | Format of the human-readable text: 'markdown' (default) for display; 'json' the same data as one JSON code block; 'none' only a one-line pointer, leaving structuredContent as the whole answer. structuredContent is always returned, so a caller that parses it should pass 'none': the character budget counts both channels, and the unread copy otherwise spends most of it. Requires the 'response_format.none' capability (see shamela_get_brief). | markdown |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | literal | morphological. | |
| root | No | Same as `term`, for older callers. | |
| term | No | ||
| by_book | No | Top 15 books by matching pages. | |
| by_author | No | Top 15 authors. | |
| truncated | No | ||
| by_century | No | Hijri century, top 15. | |
| total_hits | No | EXACT number of matching pages. | |
| by_category | No | Category names (no ids), top 15. Reflects corpus size as well as topic, never authority: التفسير tops nearly every profile because tafsir is the largest body of text here. | |
| scope_count | No | Books in scope; -1 when no scope was given. | |
| coverage_cap | No | ||
| rows_dropped | No | ||
| accuracy_note | No | Morphological counts: the analyzer is ~0.80 accurate on classical Arabic, so read them as reach, not exact tallies. | |
| books_matched | No | ||
| total_counted | No | Hits folded into the distribution. | |
| coverage_capped | No | True when the distribution is a top-coverage_cap sample: bucket counts are floors and shares indicative. | |
| normalized_tokens | No | ||
| truncation_message | No |