Server Quality Checklist

Tool Scores

• create_checkout_linkA
  5/5.0
  Behavior5/5

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

  The description goes well beyond annotations by disclosing side effects: it writes a 30-day session record, is not idempotent, spends carrier calls when no quote_id is used, never charges the card, and calls out stale-link repricing. It also explains failure conditions like missing_required_fields. This is exactly the behavioral context an agent needs.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is long but every section earns its place: main behavior, side effects, no-session cases, and parameter rules are clearly separated. It is front-loaded with the core purpose and workflow placement, and the later formatting uses scannable paragraphs and labeled parameter rules.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a 7-parameter tool with subtle override rules and special-case failures, the description is remarkably complete: it explains the quote_id interaction, fallback behavior, service matching, international customs/duty, and what the human completes on the resulting page. The output schema exists, so the description does not need to restate return structure, and it covers what the schema cannot.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Even though schema coverage is 100%, the description adds substantial semantic value: quote_id overrides most fields but not service, expired quote_ids fall back to live pricing, service matching is a case-insensitive fragment that silently falls back to cheapest, and from_zip/to_zip constraints are clarified. These rules are absent from the schema and materially change how parameters should be supplied.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description names a specific verb and resource: 'Turns a decided shipment into a payment session for buying its shipping label.' It clearly distinguishes itself from quote/session-status siblings by describing the handoff URL and session creation, and it orients the agent to the surrounding workflow with 'Use it after get_parcel_quote.'

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  It explicitly says when to use the tool ('after get_parcel_quote') and when not to ('No session is returned when... freight, oversize...'), and names the sibling get_checkout_status for checking human payment and label existence. These are concrete, actionable routing rules rather than vague context.

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

• get_checkout_statusA
  5/5.0
  Behavior5/5

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

  Beyond the readOnlyHint and idempotentHint annotations, the description discloses concrete operational behavior: no carrier call, no quote allowance, nothing changes, 30-day session lifetime, session_not_found sentinel, no PII in responses, and a rate limit of 60 checks per hour. It also warns that polling too fast is useless because nothing moves until the human acts. This is rich behavioral disclosure that materially affects how an agent should call the tool.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is longer than average but every section earns its place: statuses, polling cadence, privacy, expiry, manual-review edge case, and rate limit. It is front-loaded with the core purpose and then logically organized into statuses and parameter rules. There is no filler or tautology.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The description is complete for an agent to call this tool correctly: it names the input source, explains every possible status, gives the error sentinel for bad ids, states the rate limit, clarifies privacy, and directs onward to track_parcel. The output schema exists, so return-value details are not the description's burden. No critical operational gap remains.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Although the schema already covers session_id with a pattern and description, the description adds essential semantics: the id shape 'as_ plus a UUID', that nothing else identifies a session, that unknown/malformed/expired ids return session_not_found rather than a status, and that the id must be treated like a tracking number. This goes well beyond the schema and compensates fully for any ambiguity.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with a specific verb and resource: 'Reports where a payment session made by create_checkout_link stands.' It clearly distinguishes this tool from siblings by explaining it reads only SMKlog's own order records and later points to track_parcel for scan events. The status list further anchors what this tool does and what its output means.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives explicit when-to-use guidance: 'Poll it after handing the human the link, minutes apart rather than seconds.' It also tells the agent when to switch to a sibling tool: 'Once label_ready, feed tracking_number to track_parcel for scan events.' It adds exclusions like the manual-review request not being a checkout, which prevents incorrect invocation.

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

• get_parcel_quoteA
  5/5.0
  Behavior5/5

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

  Annotations already mark this read-only and non-destructive, and the description adds substantial behavioral context: dimension estimation behavior, purchasable-service return shape, manual review path, tasks extension behavior, label purchasing location, rate-limited carrier calls, and an 80-call hourly allowance. No contradictions 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.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Although long, the description is tightly organized with labeled sections and every sentence carries operational value. The core behavior is front-loaded and the parameter rules are grouped logically rather than repeated.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a 9-parameter tool with rich validation, rate limits, carrier integration, and sibling routing, the description covers all necessary invocation details, error cases, and fallback paths. The output schema exists, so return-value documentation is not required from the description.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, yet the description still adds critical semantics: the four parcel-dimension parameters must be sent as a set or all are ignored, product is validated against bare routes/weights/questions, from_zip must be a real 5-digit ZIP, and to_zip semantics depend on to_country. This goes well beyond the schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description names a specific verb and resource: getting live parcel shipping rates from a US origin, with explicit carriers and destination countries. It also distinguishes itself from get_price_index and create_checkout_link, so an agent can select it correctly without opening sibling schemas.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description explicitly says when to use this tool versus get_price_index, and instructs the agent to pass the returned quote_id to create_checkout_link. It also covers when a human is required (oversized, palletized, crated shipments), leaving no ambiguity about routing.

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

• get_price_indexA
  5/5.0
  Behavior5/5

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

  Annotations already mark the tool as read-only, idempotent, and non-destructive, and the description adds valuable behavioral detail: reading spends no quote allowance, invalid month shapes return invalid_month, and missing issues return issue_not_found with available_months. It also states that every issue is directly comparable month-over-month, which is useful 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.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is dense but every sentence earns its place: definition, output, use case, alternative, and parameter rules are all front-loaded in a logical order. There is no filler or repetition.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a read-only reference tool with one optional parameter and an output schema, the description covers purpose, use case, alternatives, parameter behavior, error semantics, and comparability. 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.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, but the description goes far beyond it: it specifies the YYYY-MM format, the default when month is omitted, the earliest available issue (2026-07), one-issue-per-month granularity, and the exact error responses for invalid or nonexistent months. This fully compensates for any ambiguity in the schema alone.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description names a specific resource (SMKlog US parcel shipping price index), defines its scope (six boxes, 1-20 lb, Newark to five US cities), and states the output. It also distinguishes itself from get_parcel_quote, so an agent can tell them apart without opening schemas.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  It explicitly says this is reference data for questions like US shipping costs, notes that reading spends no quote allowance, and directs callers to get_parcel_quote for a specific shipment. This is clear when-to-use and when-not-to-use guidance with a named alternative.

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

• track_parcelA
  5/5.0
  Behavior5/5

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

  Annotations already mark this as read-only, idempotent, and non-destructive, and the description adds substantial behavioral detail: it returns delivery status, latest scan events, and estimated date; it normalizes tracking numbers by removing spaces/hyphens and ignoring case; and it documents exact error responses such as tracking_number_required and tracking_not_found with status 'not_found'.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is long but every clause earns its place: scope, return value, exclusions, parameter rules, normalization behavior, carrier format expectations, and error conditions. It is front-loaded with the core action and return, then modularly covers constraints and edge cases without redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a single-parameter read-only tool with an output schema, the description is complete: it covers input requirements, normalization, validation thresholds, error responses, result shape, and sibling relationships. There is no missing information an agent would need to decide when to call it or to interpret a successful or failed call.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  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 greatly exceeds that by explaining that tracking_number is the only key, how it is cleaned, acceptable carrier formats, and the minimum length rule. This gives an agent actionable semantics far beyond the schema's simple 'Carrier tracking number from the SMKlog receipt or label page'.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a clear and specific verb ('Track') and resource ('a shipment whose shipping label was bought on smklog.com, by carrier tracking number'), then sharpens the scope by explicitly saying it is not a universal tracker for arbitrary USPS/UPS/FedEx/DHL numbers. This distinguishes it from generic trackers and from unrelated pricing siblings.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description explicitly says when to use it ('SMKlog labels only'), when not to use it ('not a universal tracker'), and names a related flow ('When the label was bought through a create_checkout_link session, get_checkout_status hands back this number at label_ready'). It also states that pricing tools are unrelated and that no order id or email is needed or accepted.

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