ipoallotment

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

With no annotations provided, the description carries the full behavioral burden. It usefully discloses the data source (registrar's official records), the exact set of return outcomes, and a privacy trait (PAN is used once and never stored). It does not cover auth requirements, rate limits, or error behavior, so it stops short of a 5.

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 front-loaded with the core purpose, followed by the privacy guarantee and a compact example. Every sentence carries useful information and there is no wasted preamble.

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 two-parameter lookup with no output schema, the description explains the return categories and the authoritative data source, which is sufficient to invoke it correctly. It leaves minor edge-case and error behavior unspecified, but the core lookup semantics are 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 description coverage is 100%, so the schema already documents both parameters, setting the baseline at 3. The example input reinforces the expected formats for ipo and pan, but the description does not add meaningful semantics beyond what the schema provides.

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 states a specific verb and resource: it takes an IPO and PAN and returns whether that PAN was allotted shares in the Indian IPO. It also enumerates the possible outcomes (allotted, not allotted, no record) and names the data source, making it clearly distinct from siblings like ipo-calendar, ipo-details, ipo-lookup, and listing-gains.

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 use case is clear from the description: checking a specific PAN's allotment status for a specific IPO. However, it does not explicitly say when to prefer this tool over alternatives such as ipo-lookup or ipo-details, nor does it state any when-not-to-use conditions.

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 no annotations, the description carries the burden and does it well: it discloses the 50-row cap, newest-first ordering, the returned fields, and even the date window embedded in the default phase. Only pagination/cursor behavior beyond the cap is unstated.

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 phase options and default are front-loaded, and every clause conveys something useful. It runs a bit long as a single sentence, but no sentence is wasted.

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?

With no output schema, the description compensates by listing returned fields (dates, price, lot size, allotment-check page) and row limits. Complete enough to call correctly; only truncation/pagination behavior past 50 rows is missing.

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%, so the baseline is 3, but the description adds real value beyond the enum by defining the default's semantics (allotment dates from 2 days ago to 7 days ahead) and giving a concrete example input.

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 gives a specific verb and resource ("Takes a phase and returns up to 50 Indian IPOs") plus the exact phases enumerated. It implicitly distinguishes itself from siblings by scoping to batch listing rather than single-IPO detail/lookup, though it never names the alternatives explicitly.

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 clearly explains the default phase and what each phase means, which signals when the tool applies. However, it offers no explicit routing guidance versus check-allotment, ipo-details, or ipo-lookup, leaving the agent to infer which sibling to pick.

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 no annotations, the description carries the full burden; it does usefully disclose the shape of the response (dates, price band, lot size, registrar, status URL, phase, listing-day gains), which tells the agent this is a rich read. However, it says nothing about fuzzy fragment matching behavior — what happens with ambiguous or zero matches — nor about data freshness or whether the call is rate limited.

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?

One front-loaded sentence gives the accepted input form and the full return payload, followed by a compact example. Every clause earns its place and there is no filler.

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?

No output schema exists, so the description correctly spends its words enumerating what comes back, which is the main thing an agent needs. For a one-parameter read tool this is close to sufficient; the remaining gap is ambiguity/no-match behavior and sibling routing.

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% and the single 'ipo' parameter already documents 'slug, id or name fragment' with the same example. The description restates that semantics plus an example input, adding only marginal value beyond the schema.

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: resolves an IPO slug/name fragment to full public details of an Indian IPO, and enumerates the returned fields. It does not differentiate from the sibling ipo-lookup, which by name sounds like an overlapping lookup operation, leaving the agent to guess which to call.

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?

Usage is only implied: passing a slug or fragment is described, and an example input is given, so the agent can infer this is the detail-fetch step. There is no explicit when-to-use versus when-not, and no mention of the sibling tools (ipo-lookup, ipo-calendar, check-allotment, listing-gains) that clearly overlap with parts of this payload.

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 no annotations provided, the description carries the behavioral burden and usefully discloses that this is a pure lookup with no network calls and that results are capped at 25. It does not cover edge cases such as empty results or matching semantics, but it gives the agent meaningful operational 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 front-loaded with the core action and result set, followed by useful behavioral context and an example input. Every sentence contributes without waste.

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 one-parameter lookup with no output schema, the description is largely complete: it identifies the input shape, return fields, result cap, and no-network behavior. Minor gaps remain around empty results and match semantics, but nothing critical is missing for correct invocation.

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%, so the query parameter is already well documented. The description adds the notion of a 'name fragment' and an example, but this largely repeats the schema's own description and example.

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 states a specific verb and resource: it takes an IPO name fragment and returns matching Indian mainboard and SME IPOs. It also specifies the result cap and return fields. It does not explicitly distinguish itself from siblings such as ipo-details or ipo-calendar, so it falls short of a 5.

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?

Usage is implied by the input being a name fragment and by the note that this is a pure lookup with no network calls. However, the description does not explicitly say when to use this tool versus check-allotment, ipo-calendar, ipo-details, or listing-gains.

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?

No annotations exist, so the description carries the full burden: it does disclose the derived-metric definition (gain vs. issue price), the two measurement points (open and close), and the sort order, which are meaningful behavioral details. It stops short of stating that it is a read-only, non-paginated query (implied by 'returns'), any rate limits, or what happens for IPOs lacking close data.

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?

Two sentences, front-loaded with the core purpose, with the example input providing maximum illustration at minimal cost. No filler.

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?

With no output schema and no annotations, the description does enough to convey what comes back conceptually (gains at open and close, newest first). It could say more about the response fields or edge cases (e.g., upcoming listings with no close price), which is the only remaining gap for a zero-annotation 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 100%, so both parameters (board enum, limit 1-100) are already fully documented with defaults and bounds. The description only restates them as 'optional board and row limit' and adds a worked example; it contributes nothing new about semantics. Baseline 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?

Names a specific resource (listing-day gains of listed Indian IPOs), the exact metrics (gain vs. issue price at open and at close), and the ordering (newest listing first). This is clearly distinguishable from the sibling tools (ipo-details, ipo-lookup, ipo-calendar, check-allotment) 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?

Usage is implied by the content ('listing-day gains'), and the example input demonstrates a typical call with defaults, but there is no explicit when-to-use/when-not or pointer to a sibling for related needs. An agent must infer the use case from the purpose statement alone.

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