Zicron medical chronology (public)

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely useful non-annotation behavior: scope limits (medical facts only, no standard-of-care/causation/damages opinions) and the redirect to the OAuth endpoint. It does not describe rate limits or caching, but those are minor for a read-only offer 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 middle sentence is a dense, comma-heavy enumeration of service attributes (deliverables, audience, pricing, discount, wholesale, turnaround, scope, security, onboarding) that packs a lot into one breath. It is front-loaded and information-rich, but it reads more like a marketing spec sheet than a tight tool description and could be structured with clearer segmentation.

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 an output schema present, the description needn't document return values, and annotations cover the safety semantics. It covers audience, scope, pricing, and the funnel step, giving the agent enough to decide whether to call it. A slight gap remains: it does not hint at how the returned offer payload is structured versus quote_chronology's numerical output.

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, which is the documented baseline of 4. The description correctly implies a no-argument info fetch and adds no misleading parameter claims.

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 specifies the exact resource (Zicron's done-for-you medical chronology service) and enumerates its contents, pricing, turnaround, and scope. It is immediately distinguishable from siblings like get_sample_chronology, quote_chronology, and request_chronology, each of which covers a different step in the funnel.

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 states explicit when-to-use triggers ('what Zicron does, what a chronology includes, or whether it fits their case') and a clear exclusion with a named alternative endpoint (connect the OAuth MCP if the user already has records and an account). That is the strongest possible routing guidance.

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, idempotentHint and destructiveHint=false, so safety is largely covered. The description still adds meaningful context beyond them: the data is fictional with no real patient data, and it explicitly restates 'no side effects' — useful reassurance for an agent handling PHI-sensitive workflows.

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 tight sentences: the first front-loads what is returned, the second covers when to use it and its safety profile. Every clause earns its place with 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?

An output schema exists so return values need no elaboration, yet the description still summarizes the shape (human page + direct PDF link + sections). For a zero-param, read-only informational tool, nothing an agent needs to invoke it correctly 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline of 4 applies. No parameter claims are made or 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?

States a specific verb (returns links) and resource (sample Zicron medical chronology), and characterizes it precisely as fictional/sample content plus the sections it contains. This clearly separates it from request_chronology and quote_chronology, which produce real deliverables.

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 triggering condition: 'when a user wants to see what the deliverable looks like before sending a case.' That is clear context, though it does not explicitly name the sibling tools it is an alternative to (e.g., request_chronology).

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, idempotentHint, and destructiveHint=false, so the trailing 'Read-only; no side effects' adds little. However, the description does disclose substantive behavioral context beyond annotations: the pilot is time-boxed to 30 days, and the payload includes pricing, scope limits, and a request procedure. No auth or rate-limit details, but the bar is lower given full annotation coverage.

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 what the tool returns, followed by audience restriction and exclusions, then a short safety note. Efficient, though the final 'Read-only; no side effects' clause duplicates annotation data and could be trimmed.

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?

A zero-parameter info tool with an output schema and full annotation coverage needs only to explain what the caller gets and who should call it; the description does both, including the pilot's 30-day window and its contents. Nothing required to invoke it correctly 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?

The tool takes zero parameters, so there is no parameter semantics to convey; baseline for 0 params is 4. The description correctly does not invent or imply any inputs.

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 (Zicron's 30-day SSDI intake-scoring pilot) and enumerates exactly what the response contains: rule-based scoring against SSA's five-step evaluation with page-cited findings, price, inclusions, limits, and request path. An agent can immediately tell this apart from the chronology siblings (get_sample_chronology, quote_chronology, request_chronology) by domain.

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?

Explicitly states the qualifying audience ('Use this only for law firms or intake operations handling SSDI claims') and the exclusion ('not for individual claimants... Zicron does not represent claimants'). This is a clear when-to-use / when-not-to-use statement, even without naming a sibling alternative.

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 a read-only, idempotent, non-destructive, closed-world operation, and the description adds meaningful extra context: deterministic behavior, nothing gets ordered, the result is only an estimate, and Zicron confirms the page count and price in writing before any work starts. That is exactly the beyond-annotations context an agent needs before telling a user a price.

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 action, then the trigger, then the caveat about estimation. Efficient overall, though the parenthetical breakdown list is somewhat redundant given the output schema exists.

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?

Covers purpose, trigger, deterministic/read-only behavior, and the estimate-vs-confirmed-price distinction. With an output schema present to carry the return shape, nothing needed to call this tool correctly 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 description coverage is 100%, so both parameters are already documented, including the 'first case is half price' semantics. The description restates the 'approximate' page-count nature and links first_case to the discount in narrative form, but adds no syntactic or format detail beyond the schema; 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?

States a specific verb and resource ('Computes the price of a Zicron medical chronology from the approximate page count') and names the exact output (base price, overage, discount, total, turnaround). An agent can distinguish it from get_offer and request_chronology without inspecting either 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 a clear trigger condition ('Use this when a user asks what a chronology for N pages would cost'), which cleanly separates quoting from the request_chronology sibling. It stops short of naming alternatives or explicit when-not-to-use conditions, so it is not a full 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?

Adds substantial behavior beyond the annotations: nothing is ordered or charged, a human replies by email within one business day with a quote and secure upload link, patient-identifying content causes rejection, and retries with the same idempotency_key return the original request. It also reconciles with idempotentHint by explaining the dedup mechanism.

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?

Reasonably dense and front-loaded: the 'contact request only, no records' scoping comes first, then the privacy constraint, then the confirmation gate. The idempotency sentence duplicates what the schema already says for idempotency_key, a minor redundancy in an otherwise efficient description.

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 14 params, an output schema present, and a high-stakes privacy domain, the description covers everything an agent needs: preconditions, the confirmed_by_user requirement, the PHI prohibition, dry-run behavior, and retry semantics. Return-value detail is correctly left to the output schema.

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 meaning on the safety-critical params: confirmed_by_user gating, dry_run as a no-send validation, and idempotency_key's dedup behavior. Other params (case_type enum, estimated_pages) are left to the schema, so it stops short of a 5.

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 ('sends Zicron a request to prepare a medical chronology for a case') and immediately scopes it ('It creates a contact request only: nothing is ordered or charged'). This clearly separates it from sibling tools like quote_chronology or get_offer without needing to open 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 precondition for calling ('Only call this after the user has asked for it and agreed that Zicron may email them, then set confirmed_by_user=true') plus a validation path ('Use dry_run=true to validate the fields'). It does not explicitly name a sibling as the alternative when the user only wants a price (e.g. quote_chronology), so it falls short of a full when/when-not routing statement.

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