Sambodh IAS

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds context about the card content and its UPSC relevance, but doesn't disclose details like pagination, formatting, or rate limits. Similar to the calibration example, this adds some value but not rich behavioral context.

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 two sentences: the first states the purpose and content, the second gives usage guidance. It is front-loaded with the primary purpose and contains no redundant or filler text.

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?

There is no output schema, but the description adequately explains what the tool returns (concept cards with specific content). With strong annotations and schema coverage, this is sufficiently complete for an agent to select the tool. It does not detail response format or pagination, but that is not critical for a read-only list tool.

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 83%, with clear descriptions for five of six parameters (days, topic, category, gs_paper, language). The description itself doesn't elaborate on parameter semantics, but since the schema covers the parameters well, the baseline 3 applies.

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 a specific action ('distilled') and a specific resource ('NewsPulse concept cards'), and explains the card content. It distinguishes from sibling tools by focusing on 'current affairs for UPSC', making its purpose unambiguous.

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 includes explicit when-to-use guidance: 'Use for any current affairs for UPSC request'. However, it doesn't mention exclusions or alternatives, so a 4 is appropriate rather than a 5.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds valuable context about the return content—what the concept card includes (bullets, relevance, explainers with links, citation)—which is especially useful given no output schema. No behavioral contradictions; the description is consistent with the read-only nature.

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 a single, well-structured sentence that front-loads the main purpose ('The full concept card behind a NewsPulse headline') and enumerates key contents concisely. No wasted words.

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 simple read tool with two parameters and no output schema, the description adequately explains what the tool returns. It covers the essential return elements and implicitly suggests a workflow (get headline then card detail). However, it lacks explicit usage guidance, preventing a perfect score.

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 parameters described (slug as 'Card slug from get_current_affairs' and language as ISO codes). The tool description itself does not add any extra parameter semantics beyond the schema, so the baseline score of 3 is appropriate.

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 title 'Read a full NewsPulse concept card' and description specify the exact resource (a NewsPulse concept card) and its contents (bullets, relevance, explainers, source citation). This clearly distinguishes it from sibling tools like get_current_affairs, which presumably lists headlines, and other quiz/topic tools.

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 gives no explicit guidance on when to use this tool versus alternatives. It doesn't mention that the slug comes from get_current_affairs (though the schema parameter does), nor does it state when this tool is appropriate (e.g., after browsing headlines). Context is only implied by the phrase 'behind a NewsPulse headline'.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds meaningful context: the sample size (3 questions), inclusion of answers and explanations, the total validated PYQ count, and the limitation that full papers are not served by this tool.

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 a single, well-structured sentence that front-loads the core function, then clarifies the sample scope and included count. Every phrase earns its place with no redundancy.

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 simple read-only tool with 2 parameters and no output schema, the description sufficiently conveys the response contents (answers/explanations, sample size, count) and scope. It could mention language behavior, but the schema default covers that.

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 coverage is 100%—both 'year' and 'language' have descriptions in the input schema. The tool description does not add extra parameter-specific semantics, so the baseline of 3 applies since the schema handles the burden.

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 real UPSC Prelims previous-year questions with answers and explanations, specifically a free 3-question sample per year. This is a specific verb+resource+scope, and it distinguishes from siblings like get_current_affairs or start_practice_quiz.

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 usage for accessing sample previous-year questions and notes that full papers are not provided (they're on the platform), but it does not explicitly name alternatives or give when-to-use/when-not-to-use directives. Guidance is implied but not explicit.

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?

Annotations already declare readOnlyHint and idempotentHint. The description adds useful context by enumerating the specific data categories returned (subjects, PYQ years, month slugs, GS-paper values), which goes beyond the annotations. However, it does not describe the output structure or potential list size.

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 a single compact sentence plus a short directive. It front-loads the tool's role and lists its contents without unnecessary verbosity. Every clause adds value.

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, zero-argument catalog tool, the description covers both the returned data categories and when to call the tool. Although no output schema exists, the enumerated categories give sufficient expectation of the response. The context from annotations and sibling tools completes the picture.

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 tool has zero parameters, so the baseline is 4. The description does not need to explain parameter details; instead, it explains the content categories that become valid parameter values for other tools, which is meaningful semantics.

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 is 'the catalog' that lists indexed subjects/topics, PYQ years, current-affairs month slugs, and NewsPulse GS-paper values. It explicitly distinguishes itself from siblings by being the parameter-value reference for search_sambodh_knowledge and quiz filters.

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?

Provides an explicit usage directive: 'Call this first when unsure which parameter values are valid.' It also frames the tool as 'the catalog behind the other tools,' making its role relative to siblings clear.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context by explaining that results are 'source-attributed passages' and instructing the agent to 'synthesize your answer from them and cite the sources.' This goes beyond annotations by clarifying the expected output format and usage protocol, though it does not cover edge cases like empty results or pagination.

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 two sentences long, front-loaded with the core action, and every clause earns its place. It states the tool's purpose, outlines the corpus, notes output characteristics, and gives usage guidance without redundancy. This is exemplary conciseness and structure.

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 no output schema, the description sufficiently conveys what the tool returns (source-attributed passages) and how to use them. It also positions the tool within the static-syllabus niche relative to siblings. It lacks explicit statements about result counts, error conditions, or the relationship between top_k and response size, but these are not critical for basic usage. The description is complete enough for an agent to invoke and interpret results correctly.

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 67%, and the description does not elaborate on parameter details beyond what the schema provides. The query parameter already has a clear description ('What to look up, phrased as a topic or question'), and subject references list_study_topics. top_k has no prose description but is constrained by defaults and min/max in the schema. The description adds no new parameter-level meaning, so it does not exceed the mid-range baseline.

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 opens with a specific verb+resource: 'Semantic search over Sambodh's indexed UPSC corpus (NCERTs + standard references).' It clearly states what it does, what corpus it searches, and that it returns source-attributed passages. This distinguishes it from sibling tools like get_current_affairs and get_pyq_sample by scoping it to static-syllabus content with a retrieval-and-synthesis workflow.

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 gives clear context: 'Use for static-syllabus questions (history, polity, geography, economy...).' This implies it is not for current affairs or dynamic topics, but it does not explicitly name an alternative tool or state a 'when-not-to-use' exclusion. Since it provides a clear usage domain without explicit exclusions, it earns a 4 rather than a 5.

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?

Annotations already declare readOnlyHint and idempotentHint, covering the safety profile. The description adds a critical behavioral constraint about not revealing answers and references the grading tool, which provides valuable context beyond the structured hints.

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 only two sentences, with the first stating the action and the second delivering an important workflow instruction. Every word contributes, and there is no redundancy or fluff.

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?

The combination of schema, annotations, and description covers the purpose, safety profile, and key workflow link to submit_quiz_answers. It could explicitly detail the return format or question count behavior, but given the simple nature and absence of an output schema, it is sufficiently complete.

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 already provides descriptions for 5 of 6 parameters, so the baseline is set. The tool description itself adds no parameter-specific meaning, relying on the schema, which adequately documents the parameters.

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 starts an MCQ quiz from a validated question bank, with a specific action and resource. It distinguishes itself from sibling tools like get_pyq_sample (which merely fetches sample questions) and submit_quiz_answers (which grades responses).

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 explicit workflow guidance: never reveal answers before attempts and grade via submit_quiz_answers. This gives clear context on when to use this tool relative to the grading tool, though it doesn't explicitly discuss all alternative tools.

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 idempotentHint=true and destructiveHint=false provided by annotations, the description does not need to restate them. It adds value by disclosing server-side grading and the output format. 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 only two sentences, front-loaded with the core action. Every word contributes, with no repetition of schema information.

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?

Despite lacking an output schema, the description clearly states the return values. It also notes that grading can be done for partial answers, which is critical context. The tool has few params and is well-scoped, so this is complete.

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 documentation covers 100% of the parameters with descriptions, so the baseline is 3. The description does not add further parameter details, but none are needed.

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 verb 'Grade' and the resource 'quiz attempt', and specifies it returns per-question verdicts and an overall score. This effectively distinguishes it from sibling tools like start_practice_quiz, which initiates an attempt.

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 provides clear context for when to call ('once the user has answered'), but does not explicitly mention alternatives or when not to use it. The schema reference to 'quiz_id from start_practice_quiz' indirectly signals the workflow with a sibling tool.

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