Intentions MCP Server

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

Annotations only give readOnlyHint and openWorldHint=false; the description goes well beyond them, disclosing the three operating modes, per-mode limits (up to 5 compared dates, up to 31-day scan), free-tier gating on ranges, and the shape of the result (score 0-100, verdict, per-layer breakdown, adverse alerts). No contradictions with 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 trigger condition, then modes, then constraints, then alternatives — a sensible ordering with little waste. The example-domain list ('trip dates, launch days, interview/meeting days...') is longer than strictly necessary but aids intent matching, and the multilingual trigger example is a useful matching hint.

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, so the description compensates by describing the return payload (score, verdict, per-layer breakdown, element breakdown, adverse alerts). Combined with the mode limits, tier constraints, and sibling routing, nothing material is missing for a 6-parameter tool with nested objects.

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 about how the date parameters combine into modes — single date, comparison against targetDate, or range scan — and restates the 31-day range cap and free-tier window. It stops short of explaining categories or the birthInfo null convention, which the schema already covers.

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 concrete trigger and resource: 'Call when the user asks about timing a decision for a specific date, or wants to pick the best day from a multi-day window.' It is immediately separable from siblings because it names the day-granularity scope and points at `intentions_ask_month` and `intentions_ask_hour` for other granularities.

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?

Explicit routing rules: multi-month windows go to `intentions_ask_month`, hour precision to `intentions_ask_hour`. It also states the free-tier condition that selects between modes ('a range must sit inside the past week and the week ahead; single and compared dates are free anywhere'), which is exactly the kind of when-to-use decision an agent needs.

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 declare readOnlyHint=true; description adds extensive behavioral context: pro subscription required, free tier error handling, three modes (single, compare, scan), internal mapping to 2-hour blocks, 23:00-23:59 rolls day forward, output includes window span with no timezone offset. 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?

Description is concise considering the complexity; front-loaded with purpose and usage. Every sentence adds value, but could be slightly better structured (e.g., separate sections for modes, edge cases, output). Still effective and efficient.

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 the tool's complexity (7 params, nested objects, no output schema), description covers usage context, subscription behavior, all three modes, edge cases (hour roll), and output format (window, score, verdict, alerts). No output schema but description sufficiently informs agent of return structure.

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%, baseline 3. Description adds meaningful details beyond schema: explains targetHour auto-rounding, compareHours deduplication rule, bestInDay.top default, and output window format. Only minor gap: no default for category or targetDate described beyond 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?

Description clearly states the tool is for timing within a specific day (best hour, morning vs afternoon). Uses specific verbs like 'Call when the user asks about timing within a specific day' and distinguishes from siblings by naming alternatives (intentions_ask_day, intentions_energy_chart).

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 when to use (user asks about timing within a day), mentions pro subscription requirement and free tier behavior with clear fallback suggestions. Provides alternatives for different granularity (day-level analysis, visual overview).

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 only declare readOnlyHint=true and openWorldHint=false, yet the description adds substantial non-obvious behavior: the three operational modes, the 5-month compare cap and 12-month scan cap with top-5 return, and the free/Pro pricing boundaries tied to date range. That is genuine context the annotations cannot convey.

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 trigger condition, then modes, gating, and returns, then sibling routing — a logical order. It is dense but slightly redundant, restating the free/Pro boundary that the monthRange schema description already carries.

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 carries the return burden and does so ('month score, element breakdown, adverse alerts'). Combined with modes, gating rules, and sibling routing for a 6-param nested tool, an agent has everything needed to call it 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 coverage is 100%, so the baseline is 3, but the description earns more by reconciling the confusing schema (compareMonths maxItems=4) into 'compare up to 5 months' via targetMonth, and by stating the 12-month scan cap returns only the top 5. It does not explain the category enum weighting or birthInfo override 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 precise trigger and resource: month-granularity intention analysis for selecting a month. It explicitly differentiates from siblings by naming intentions_ask_day and intentions_ask_hour and the granularity condition that selects each, so an agent can route without opening another 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 concrete example phrasings ('how is next month', 'best month in 2026 to X'), enumerates decision categories (trip-month, launch, content calendar, quarterly/annual), and names the alternative tools with the exact condition that switches to them (day vs hour precision).

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 establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered by structured data. The description adds the useful year window constraint and the shape of the result set, but says nothing about rate limits, cost, or how birthInfo override behaves at runtime.

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?

Four tight sentences, front-loaded with the trigger condition before the alternatives and the boundary constraint. Every clause carries distinct information; no restatement of the tool name or padding.

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 usefully enumerates the return payload (score, verdict, alerts, element dimensions) and covers routing and the year window. It is nearly complete, though it omits any note on what the optional birthInfo override does to results beyond the schema's own wording.

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 each parameter is documented in the schema, so the baseline would be 3. The description does add one substantive constraint not obvious from the parameter list alone: the hard currentYear-3..currentYear+3 window that governs targetYear, reinforcing the allowed range for a key parameter.

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 (ask) plus resource (year-level intentions) and enumerates the exact payload: year score, verdict, adverse alerts, and element dimensions. It also explicitly distinguishes itself from intentions_ask_month and intentions_ask_day, so an agent can route 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?

The first clause names the trigger condition with concrete user phrasings ("how is 2026", "今年怎么样", "what's next year like overall"), and the second sentence routes month/day-precision requests to the named sibling tools. The valid window is stated as an explicit boundary, leaving nothing to inference.

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 only cover readOnlyHint/openWorldHint; the description adds substantial behavioral context beyond them: the free/Pro gating per mode, the exact error payload on the free tier, and the date-boundary rules for what stays free. This is exactly the tier/authorization detail an agent needs before calling.

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 use case, then the return shape, then the tier rules — all useful. It is dense and runs long in a single trailing sentence, but no clause is 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, the description still explains the return format (ASCII chart, two-hour blocks/days/months) and the tier-failure behavior. An agent has everything needed to choose and invoke it 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 coverage is 100% and the `period` description already maps hourly/weekly/yearly to blocks, days, and months (including the Pro note). The description largely restates this, adding only the 'omit `date` for this week/year' default nuance, so 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?

States a specific verb and resource (renders an ASCII energy chart) and explicitly distinguishes itself from narrative siblings by naming the exact intent that selects it ('visual overview rather than a narrative answer'). It even cites the sibling `intentions_ask_hour` as the source of the same hour-resolution scores.

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 concrete trigger phrases ('show me this week', 'chart for today', '看一下图') plus the negative condition (use narrative tools instead of prose answers). It further routes by tier, telling the agent which modes are free versus Pro and that a `subscription_required` error suggests alternatives.

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 declare readOnlyHint=true and openWorldHint=false, so the safe-read profile is already covered. The description exceeds that bar by disclosing the return shape, that unknown fields come back as null, the quota mechanic (profileChanges.remaining/resetsAt, calendar month UTC), and the instruction to warn the user when remaining is 0. Since it goes well past the annotation bar, this is strong, though it is largely return-value content.

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 purpose, then usage, then return semantics and quota caveat. Despite being dense, every sentence carries distinct operational value (merged payload, null unknowns, quota exhaustion warning) 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?

With no output schema, the description fully carries return-value disclosure, including the exact object shape, null semantics, and quota fields. An agent has everything needed to call it and interpret the result 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?

The tool takes no parameters, so there is nothing to document beyond the schema; a baseline 4 is appropriate. The description offers no parameter syntax because none exists.

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+resource ('Fetch the user's currently stored birth info') and clearly contrasts with the sibling it complements (intentions_set_birth_info). An agent immediately knows this is a read of the stored profile, distinct from the ask_* input 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?

Explicitly instructs when to call it: 'Use this before intentions_set_birth_info when updating an existing profile so you can send back a complete merged payload.' Names the alternative, the condition, and the reason, plus notes 'No quota cost' which removes a reason to avoid calling it.

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 cover write vs. read and idempotency, but the description adds substantial context beyond them: whole-payload replacement semantics, explicit null requirements, a 3-per-calendar-month quota for date/gender/known-hour changes, which edits are quota-free, and the fact that the quota count is exposed by a sibling tool. This is behavior an agent could not infer from the structured fields.

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 replacement semantics, null handling, update workflow, and quota — every sentence carries needed information. It is dense and slightly run-on, but nothing is redundant with the schema or title.

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 six-parameter write with no output schema, the description covers everything an agent needs: replacement semantics, null conventions, the read-merge-write update path, rate limits with an escape hatch, and the return payload ('Returns the element profile'). Nothing material 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. The description goes beyond it by explaining the explicit-null convention ('hour: null' for unknown time, 'gender: null' for unspecified) and the all-fields-required replacement rule, plus the cross-field constraint that minute requires hour. It doesn't add format details for year/month/day, but the schema already handles those.

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: 'register the user's birth date/time/gender'. It also names the relevant sibling (intentions_get_profile) for the update path, so an agent can distinguish writing the full profile from reading it without opening 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?

Explicitly says to call once, that each call is a full replacement requiring all 6 fields, and precisely which sequence to follow for a single-field update (fetch via intentions_get_profile, merge, resend). It even scopes the rate limit to specific field changes, leaving no ambiguity about when this tool is the right choice.

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