Gravitate

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

Annotations already cover read-only, idempotent, closed-world and non-destructive, and the description adds genuinely new context: the tool is free, needs no account/payment/credits, and explicitly performs no image generation, bookings, or identity inference. It stops short of describing the shape of the returned plan, which matters since there is no output schema.

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?

Three tight sentences with no filler; the exclusions pack real information. The 'Free; no account, payment or Gravitate credits' line is front-loaded before the purpose statement, which slightly delays the core verb but is defensible as a call-friction signal.

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 5-param, read-only, no-output-schema tool, the description covers cost, trigger, scope limits and personalization inputs. The main residual gap is what the returned plan looks like (structure, length), which the agent has to discover by calling.

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?

With 60% schema coverage, the description compensates by tying persona ('single-dad/returning-to-dating context'), setting, photographer and the 15/30/60 minute options to the tailoring behavior. It also reinforces the persona constraint ('no inference about the user's identity'). Only locale goes unmentioned, and that is fully self-documented in 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 deliverable: a 'practical 15, 30 or 60 minute dating-photo shoot plan' that tailors curated advice to persona, setting and photographer. That is distinguishable from score_photo_observations (scoring) and get_service_status, though the boundary with get_photo_guidance is only implied, not stated.

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?

'Use when a user wants a practical 15, 30 or 60 minute dating-photo shoot plan' gives an explicit trigger condition. The closing exclusions (no image generation, bookings, or identity inference) add useful when-not boundaries, but no sibling tool is named as the alternative for out-of-scope requests.

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 context beyond the read-only/idempotent annotations: free access with no auth or credits, English/French locale support, returned editorial content with update dates and canonical sources, and clear safety limitations. This tells the agent what to expect operationally and content-wise.

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-loads the free-access facts and the core resource/purpose, then gives the catalog entry point and return details. The disclaimer sentence is somewhat long but earns its place by preventing misuse around personalized advice and boundary-crossing tactics.

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 only two optional parameters, no output schema, and strong annotations, the description is complete: it covers access cost, supported locales, content scope, entry workflow, return contents, and safety boundaries. 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% and both enum parameters are well described in the schema. The description still adds value by instructing the agent to begin with topic=catalog and by characterizing the topic set as fixed published guides rather than private stories or profile text.

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: retrieve published English/French coaching articles for single dads, dating after 40/divorce, and reconnection questions. This clearly distinguishes it from siblings like get_photo_guidance, get_profile_example, and build_photo_shoot_plan, which cover different domains.

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 tells the agent to start with topic=catalog to choose a guide, and frames the tool as free with no account/payment/credits. It doesn't name sibling alternatives or state when not to use it, but the domain separation from photo/profile tools is evident.

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 read-only, idempotent, non-destructive, closed-world behavior. The description adds genuinely useful non-schema context: it is free with no account, payment, or credits required, and responses include a source URL. It stops short of describing result structure or rate limits, but covers the main behavioral questions.

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-loads the cost/auth facts, then use cases, then scope exclusions, with no filler. The terse, semicolon-heavy opening is dense but still readable and appropriately short for a simple retrieval tool.

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 two-parameter read-only guidance lookup with no output schema, the description supplies enough: cost, auth, languages, source URL in results, and scope limits. The main missing piece is fuller semantics for the topic enum, which would complete 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?

Schema coverage is 50%: locale is documented in the schema, but the topic enum values are not explained anywhere. The description adds only indirect hints about topic choice ('understanding the Gravitate rubric', 'methodology before ranks') and mentions English/French, but does not clarify values such as 'developers' or 'attractiveness'.

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 ('Retrieves published English/French guidance') and scopes the subject matter to dating-profile photos and the Gravitate rubric. It explicitly distinguishes itself from siblings by saying it 'Does not inspect images', which separates it from score_photo_observations.

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 use cases (choosing dating-profile photos, understanding the rubric, asking about authentic image improvements) and clear exclusions (no image inspection, no general relationship/reconciliation advice). It adds sequencing guidance ('Choose methodology before supplying ranks') but does not name sibling tools as 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 already cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds what they cannot: it is free with no account, payment or credits required, and the content is a clearly fictional, annotated example from a published article, not a real customer or proof of improved matches. These cost/auth preconditions and content disclaimers are exactly the extra context an agent needs before presenting results.

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-loads the free/no-account precondition, then the when-to-use trigger, then the content description and a compact list of things the result is not. Four tight sentences with no filler, though the negation list is dense and could be trimmed to one clause.

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 only two enum parameters, full schema coverage and no output schema, the description still tells the agent what comes back (an annotated example bio and photo lineup), in which languages, at what cost, and what the result must not be represented as. Nothing material 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 coverage is 100%, so 3 is the baseline, but the description adds intent beyond the enum values: it explains locale as the response language (English or French) and reinforces that persona must be chosen from what the user actually asked for rather than inferred. That selection rule adds behavioral meaning the schema only partially encodes.

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 — retrieves a fictional, annotated example profile (bio plus photo lineup) in English or French — and explicitly negates adjacent capabilities it is not (image analysis, evidence of improved matches), which separates it from siblings like score_photo_observations and get_photo_guidance. It stops short of naming those siblings directly.

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?

"Use when asked for an example bio and photo lineup for a single dad or someone returning to dating" gives a clear triggering condition, and "Choose only the persona requested by the user" constrains selection. No alternative tools are named, so routing when the user wants guidance rather than an example is left implicit.

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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description contributes real added context: it is free, requires no account or payment, reports 'actual enabled capabilities' (as opposed to advertised ones), and will not resume paused services. However, it offers no detail on response structure or on what 'current limits' look like.

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 short sentences, each carrying information, with the capability list and the 'does not enable' caveat in a sensible order. The opening 'Free; no account, payment or Gravitate credits' is slightly awkward and puts commercial framing ahead of the purpose.

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 does the necessary work of summarizing what comes back (enabled capabilities, free pricing, current limits). For a single-optional-parameter, read-only probe this is nearly complete; only the shape of the returned capability data is left unspecified.

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?

Only one optional parameter (locale) exists, and the schema documents it at 100% coverage, including the en/fr enum. The description adds nothing about locale behavior, so it sits at the baseline where the schema does all the work.

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 combines a clear resource ('Gravitate availability') with the specific capabilities it reports on: photo analysis, image generation, payments, and guidance. It is easily distinguished from the sibling tools (build_photo_shoot_plan, get_photo_guidance, score_photo_observations), but it never names or explicitly contrasts itself with them.

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?

'Use when checking whether Gravitate can analyze photos, generate images, accept payments, or provide guidance' states the triggering conditions explicitly, and 'Does not enable paused services' draws a boundary on what this call will not do. It lacks any pointer to alternative tools for follow-up actions, which keeps it short of a full when/when-not/alternatives statement.

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?

Beyond the readOnly/idempotent annotations, the description discloses cost and auth ('Free; no account, payment or Gravitate credits'), the processing model ('performs no vision or AI inference'), and explicit non-goals (beauty, age, identity, attraction percentiles, match probability). Those non-goals are the key behavioral fact for an agent deciding whether this tool answers a user's question.

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?

Dense and largely waste-free, with limits and prohibitions collected compactly. Minor weakness: it opens with pricing/credits rather than the purpose, so the key action statement is pushed to the second sentence.

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 carries the return-value burden; it says the tool produces totals and applies caps but never describes the response shape (per-observation scores vs. aggregate, ordering). Everything else an agent needs to invoke it correctly is present.

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 67% and already documents the rubric mapping and caps, yet the description still adds unstated constraints: ranks must be explicitly supplied, observations are anonymous and capped at six, no image/URL inputs. It does not clarify the observation_source enum values in prose, leaving part of the parameter space to 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 object — 'Calculates gravitate-v1 totals and caps for 1–6 anonymous observations' — which no sibling (build_photo_shoot_plan, get_photo_guidance, get_service_status) could be confused with. It also bounds the input scope (1–6 anonymous observations) in the same sentence.

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 preconditions are given: 'Use only with explicitly supplied 1–4 ranks ... after reading the methodology' and the hard exclusion 'Never invent ranks from a request without observations.' The negative case ('Accepts no images/URLs') closes the most likely misuse path.

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