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

The description discloses that 'login' opens a Chrome window, waits for user sign-in, saves cookies, and closes Chrome. Saving cookies is a write operation that modifies session state. However, the annotations declare readOnlyHint: true, which implies the tool does not modify data. This directly contradicts the described behavior. Therefore, the description contradicts the annotations, warranting a score of 1.

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 two sentences long, front-loaded with the session purpose, and each sentence earns its place. It is concise without unnecessary detail, and the critical usage instruction ('run it only when status says not logged in') is included.

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 tool with two parameters and no output schema, the description covers both actions and their purpose. It explains that 'status' reports session validity and user identity, and 'login' handles the sign-in flow. The missing piece is explicit output format for 'status', but the description states what it reports, which is sufficient for an agent 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?

The description explains the meaning of the two actions, which is not fully covered by the schema (the 'action' parameter has an enum but no descriptive text). The 'timeoutSeconds' parameter is already described in the schema. With schema coverage at 50%, the description compensates by clarifying the action values, adding 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?

The description clearly states the tool's purpose: managing an Ancestry login session. It specifies two concrete actions, 'status' and 'login', and explains what each does. It is distinguishable from sibling tools like 'tree', 'person', or 'fact', which handle data operations rather than session management. The verb 'login session' is specific and unambiguous.

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 description gives explicit guidance for when to run 'login': only when status says not logged in. It also notes that normal use does not require a browser, implying 'status' is the common operation. It does not explicitly mention alternatives, but sibling tools are unrelated, so the usage context is clear. The exclusion ('run it only when...') is a strong guideline.

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?

Despite minimal annotations (readOnlyHint=false, destructiveHint=false), the description provides substantial behavioral details. It clarifies what each action does: tests require testGuid, matches includes filters and sort, add_to_group/remove_from_group modifies group memberships, set_note explicitly says 'empty clears', match_detail returns shared cM/segments and predicted relationship, and ethnicity gives estimate regions. This goes beyond the schema by explaining side effects and output content, though it omits persistence and error behavior.

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 extremely dense, packing nearly all tool information into a single run-on paragraph. Every piece of information is relevant, but the lack of line breaks or bullet points makes it hard to parse. It front-loads 'AncestryDNA' but then presents a lengthy stream of actions and filters. It is more a reference manual than a concise summary, though it avoids fluff.

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 (19 parameters, 8 actions, no output schema) and sparse annotations, the description is incomplete. It hints at outputs for match_detail and ethnicity, but not for matches, groups, or mutations. It does not explain prerequisites like needing a testGuid before querying matches, pagination semantics for page, or what fields are returned. An agent would need to infer many calling conventions, making this below the minimum viable completeness for such a multi-action 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?

With 0% schema description coverage, the description carries the burden of explaining parameters. It does well by mapping filters to actions: minCm/maxCm, parentalSide enumerations, trees, groupIds ('2 = starred'), nameSearch, sortBy values, pageSize limit, and sharedWithMatchGuid semantics. It also notes action-specific required parameters like matchGuids+groupId for add/remove. However, a few parameters (page, matchGuid) are not explicitly tied to actions, so compensation is not complete.

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 clearly indicates the tool covers AncestryDNA functionality and enumerates all actions: tests, matches, groups, add/remove group, match detail, set note, ethnicity. This is specific enough to distinguish from sibling tools like tree, person, or search_records, which focus on other genealogy data. However, it lacks a single crisp verb phrase summarizing the tool's overall purpose, instead presenting a list of sub-actions.

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 description gives no explicit guidance on when to choose this tool over siblings. It implies AncestryDNA-related use by naming DNA-specific actions and filters, but it does not state any criteria or exclusions. There is no mention of alternatives, prerequisites, or scenarios where another tool would be more appropriate, leaving the agent to infer.

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 destructiveHint=true already flagging danger, the description adds important behavioral detail beyond annotations: 'edit (all fields replaced)', delete is an available action, and date strings outside the approved formats are 'stored unparsed and never matches records or hints.' This meaningfully discloses side effects and data-matching consequences.

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 dense but every sentence carries essential information: resource scope, actions, dependencies, date grammar, and place ordering. It is front-loaded with the core purpose and then expands into constraints. It could be better organized with clearer separation between actions, but it avoids wasted words.

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?

The description covers many operational details and constraints, especially date parsing and citation/media workflows. However, it does not specify required parameters per action (e.g., what an 'add' minimally needs beyond action), and with no output schema it also does not describe return behavior. These are meaningful gaps for a complex 15-parameter 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 only 33%, but the description substantially compensates by explaining action-specific parameter roles: spouseId for relationship events, assertionId for edits, citationId with databaseId/recordId for record citations, mediaId for media attachments, and detailed date/place formatting. Some parameters remain unexplained or implicit, such as treeId, showOnLifeStory, and description, so it is not a perfect compensation.

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 clearly identifies the resource as 'Facts/events on a person' and enumerates the supported action verbs (list_types, add, edit, delete, attach/detach citation/media). This makes the tool's domain and scope obvious and distinguishes it from sibling tools like person, source, and record.

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 description provides rich operational guidance, such as edit requiring an assertionId from person.get, relationship events requiring spouseId, and citation attach needing databaseId+recordId for record citations. However, it never explicitly states when to choose fact over alternative sibling tools or when not to use it, so the usage context is implied rather than explicit.

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 state readOnlyHint=false and destructiveHint=false, and the description does not contradict these. It adds context by explaining the meaning of set_state values (rejected/deferred/pending) and noting that compare shows the Review page. It does not explicitly disclose side effects of set_state beyond state changes, but that is implied. The description gives enough behavioral context beyond 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?

The description is information-dense but well-organized. It front-loads the domain, then breaks down actions in a compact list, and ends with the acceptance routing. There is no fluff, though it is slightly long. It earns a high score for efficiency, though not perfect conciseness due to its length.

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 tool with 11 parameters, an action enum, and no output schema, the description covers the main actions and the acceptance alternative, but it omits which parameters are required for each action (e.g., set_state likely needs hintId and state) and what each action returns (e.g., summary returns counts, list returns a page of hints). This leaves gaps for an agent attempting to construct calls 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 description coverage is only 18%, so the description must compensate. It explains the action enum and links firstName/lastName/page/pageSize to the list action, and explains the state enum for set_state. However, key parameters like hintId, collectionId, and recordId are not explained in the context of compare or set_state, leaving the agent to infer their purpose from the schema names. It partially compensates but not fully for the low coverage.

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 clearly states the tool's domain (Ancestry hints) and enumerates the four actions with concise explanations (summary counts, list pending hints, compare side-by-side, set_state for rejection/deferral). It explicitly distinguishes from sibling tools by directing acceptance to record.save_to_person and media.copy_from_tree, so an agent can tell exactly what this tool is for versus alternatives.

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?

Provides explicit guidance on when to use this tool (for hint management and comparison) and when not to (for acceptance), naming the specific sibling tools to use instead. It also instructs to compare before accepting, which is a clear usage rule. No ambiguity remains about the intended workflow.

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 flag destructiveHint=true and readOnlyHint=false, and the description adds meaningful behavioral detail beyond that: download can write to outPath or return base64 with maxSide scaling, upload maps a local file to a person gallery, update keeps omitted fields, and copy_from_tree only works from a public tree. No contradiction with the annotations was found.

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 packs an entire multi-action API into a single compact sentence, with each action clause earning its place. It is dense and could benefit from line breaks, but it is efficient and front-loads the resource type before detailing the actions.

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 tool with 19 parameters, 8 actions, no output schema, and only 21% schema-description coverage, the description provides a decent action roadmap but is incomplete. It omits return-value information, per-action required parameters, pagination behavior, and the meaning of cropping and primary-photo parameters, which an agent would need to invoke the tool correctly in many cases.

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 only 21%, so the description must compensate, and it does cover several parameters by embedding them in action explanations: outPath, maxSide, filePath, personId, title, date, description, location, and destPersonIds. However, key parameters such as mediaId, cropX, cropY, cropSize, page, sourceTreeId, sourcePersonId, and asPrimaryPhoto are left completely unexplained, and it is unclear which parameters each action requires.

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 opens with the resource domain ('Photos, documents and stories in a tree') and then enumerates eight specific actions as verb+resource pairs: list, get, download, upload, update, set_profile_photo, copy_from_tree, delete. It even differentiates from sibling fact by pointing out that attaching media to a fact is fact.attach_media. An agent can tell exactly what this tool is for.

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 description gives contextual usage hints for many actions, such as listing for a person vs. the whole tree when personId is omitted, copying from a member's public tree into destPersonIds, and that update preserves omitted fields. It also explicitly routes fact attachment to fact.attach_media. It lacks broader when-not-to-use guidance versus all siblings, but the action-specific notes are strong.

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?

The description adds important behavioral context beyond annotations by disclosing that send 'sends real mail to a real person' and requires user confirmation, which is a meaningful side-effect warning. It also notes that member_profile returns a public profile. There is no contradiction with the annotations; readOnlyHint=false and destructiveHint=false are consistent with a send action.

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 compact and front-loaded, moving from the domain to a scannable action list with useful parentheticals. It wastes little space, though the dense action list could be slightly better structured with line breaks.

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 multi-action tool with no output schema and sparse parameter documentation, the description covers the main actions and the critical send-confirmation behavior, which is good. However, limit semantics, the notifications action's behavior, and return shapes are unspecified, leaving meaningful gaps for an agent attempting 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?

The schema has 0% description coverage, so the description carries the parameter-semantics burden. It does map actions to key parameters (conversationId for get_messages, userId for member_profile, conversationId/toUserId for send), but it does not explain the limit parameter or clarify which actions it applies to. Content is also left implicit.

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 clearly identifies the tool's domain as 'Ancestry member messaging and notifications' and enumerates the specific supported actions, so an agent understands what the tool does. It does not explicitly contrast with sibling tools, though the messaging scope is distinct enough to separate it from 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?

The description gives actionable usage context, such as using conversationId to reply and toUserId to start a new conversation, and warns to confirm with the user before sending real mail. It does not explicitly state when not to use this tool or point to alternatives, so it stops short of full exclusion 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?

The description explicitly discloses that save_notes 'replaces the whole note', a destructive overwrite behavior. This contradicts the annotation destructiveHint=false, which signals the tool is not destructive. Per the rubric, a description that contradicts annotations receives a 1.

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 one dense, front-loaded line that lists all actions and embeds caveats without padding. Every clause carries information and no space 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?

For a six-action tool with no output schema, the action menu covers most invocation paths, but it omits return semantics for get_notes, add_tags, remove_tags, and create_custom_tag. The annotation contradiction also leaves the tool's safety profile unclear.

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 only 25% schema description coverage, the description compensates by explaining the action enum and key parameter relationships (tagIds with custom=true, list_tags returns category ids). However, it leaves name, note, and description parameters unexplained, so it doesn't fully close the gap.

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 opens with 'Research notes and MyTreeTags on a person', a clear verb+resource statement, and enumerates all six actions, making the tool's scope obvious. It does not explicitly distinguish itself from sibling tools like person or record, so it misses the top tier.

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 description gives clear how-to guidance inside the action menu: save_notes replaces the whole note and should be read first to append, and add/remove_tags requires custom=true for custom tag ids. It doesn't state when to choose notes_tags over sibling tools, but the action-specific caveats are strong.

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 signal destructiveHint=true and readOnlyHint=false, and the description adds rich behavioral detail: delete is permanent and requires displayName to match exactly, update keeps omitted fields, add/update default to deceased, living people are hidden from shared/public views, and remove_relationship unlinks without deleting either person. These details go well beyond 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?

Though long, the description is densely packed and action-keyed, with each clause providing distinct operational facts and no filler. The semicolon and middle-dot structure makes the eleven actions scannable despite the length.

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 high-complexity tool with 27 parameters and no output schema, the description covers a remarkable amount: list/get/find return behavior, deletion permanence and safety, living-person privacy, and modifier semantics. However, a few actions (relationship_to_home, add, link_existing, delete) lack explicit return-value or post-condition details, so it is nearly complete but not fully exhaustive.

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 only 26%, so the description carries significant weight. It explains type codes (F/M/C/H/W), relationship values, modifier codes (pcb/pca/pcs/pcf/spu/spx/spp), the delete displayName requirement, list pagination and name filtering, includeSourceDetails, and anchorPersonId semantics. A few parameters such as view, generationsUp/generationsDown, and originalModifier remain undocumented, so it is strong but not exhaustive.

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 identifies the resource as people in a tree and enumerates eleven concrete actions (list, find, get, add, update, delete, etc.), so an agent knows exactly what operations are available. While it lacks a single verb+resource phrase, the action inventory is specific and clearly separates this tool from siblings like fact, media, or notes.

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 description gives clear within-tool selection guidance: 'brief rows — use get for details,' add vs. link_existing vs. update vs. change_relationship distinctions, and the note about read-only access on public trees. It does not explicitly contrast with sibling tools, but it provides enough context for choosing the correct action.

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?

The description discloses that it performs same-origin fetch with cookies and adds CSRF for hintsui/DNA APIs, which is valuable behavioral context beyond the annotations. The annotations already indicate destructiveHint=true, and the description reinforces the 'escape hatch' nature. It doesn't detail failure modes or rate limits, but the core behavioral traits are disclosed.

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 compact and front-loaded with the key purpose ('Escape hatch'), then provides the mechanism, usage condition, example, and pointer to docs. Every sentence earns its place.

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 low-level escape hatch tool with no output schema, the description covers the essential context: what it does, when to use it, how it authenticates, and where to find more info. It could mention response format or error handling, but the pointer to docs/endpoints.md mitigates that gap.

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 0%, so the description must compensate. It explains the 'path' parameter with an example and mentions 'dnaContext' implicitly via 'CSRF added for hintsui/DNA APIs'. However, it doesn't explain 'method' or 'jsonBody' beyond what the schema provides. The description adds some meaning but not full compensation for the 0% coverage.

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 clearly identifies this as an escape hatch for performing arbitrary ancestry.com requests through the logged-in browser, with a concrete example path. It explicitly distinguishes itself from the sibling tools by saying 'Only when no action above fits.'

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 description explicitly states when to use this tool: only when no other action fits. It also provides a concrete example and points to docs/endpoints.md for known endpoints, giving clear guidance on how to use 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?

The description reveals important behavioral details beyond the minimal annotations: download_image writes a file via outPath, save_to_person creates citations and merges events, updateExisting replaces facts, saveAsAlternate keeps both, and includeRelatives adds/linked relatives. Some actions such as image_index and shoebox_remove get only terse mentions, so it is not fully exhaustive.

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 dense and front-loaded with the overall scope, then organized by action. There is no filler, but the long run-on sentence with semicolons and nested parentheticals makes it harder to parse quickly.

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 15 parameters, 8 actions, and no output schema, the description covers the critical return/effect semantics for get, download_image, suggest_places, and save_to_person. However, image_index, shoebox_list, shoebox_save, and shoebox_remove lack comparable detail, and some parameter-purpose relationships are left to inference.

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 only 27%, but the description compensates by explaining key parameters: maxSide and outPath, events options and default, updateExisting/saveAsAlternate/updateName semantics, includeRelatives usage, and suggest_places term. A few parameters like title, collectionId, and recordId remain semantically thin or unexplained.

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 clearly identifies a resource ('Historical records and places') and enumerates specific actions with concrete verbs and object details (get, image_index, download_image, save_to_person, suggest_places, shoebox_*). It is unambiguous about what the tool does, though it does not explicitly differentiate itself from sibling tools like search_records.

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?

Each action carries enough context to imply when it is appropriate, e.g. 'save_to_person ... exactly like the site Review page' and 'suggest_places ... place autocomplete → gpid'. There is no explicit when-to-use versus sibling alternatives or when-not-to-use guidance, so usage is implied rather than stated.

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?

Despite readOnlyHint=true already covering safety, the description adds substantial behavioral detail: default matching is fuzzy everywhere (results ranked, not filtered), wildcard rules, yearTolerance semantics (0 = exact, 1/2/5/10 = ±years, omit = fuzzy), and return behavior (up to 50 hits with indexed fields and ids). It also explains that collectionFocus re-ranks rather than filters, and that extraParams passes any other site query parameter. This goes well beyond what annotations provide.

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 long but every sentence carries necessary information. It is logically organized: purpose, input formats, matching behavior, event object details, wildcard rules, search strategy, special parameters, and return info. It front-loads the core purpose and progressively details advanced usage. There is no filler or redundancy.

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 tool with 32 parameters, nested objects, and no output schema, the description is remarkably complete. It explains how to construct effective searches, the meaning of key parameters, result size, and how results link to downstream tools (record.get, record.save_to_person). It also mentions related tools like record.suggest_places for gpid. The only missing detail is the exact JSON structure of the returned hits, but that's not required without an output schema and the description indicates the necessary information.

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 only 16%, so the description must compensate. It does: it explains name format ('First Last'), year format (4-digit), place format (free text with gpid), the cumulative matching levels for firstNameMatch/lastNameMatch, the structure and semantics of event objects (year, yearEnd, yearTolerance, place, gpid, placeScope), wildcard syntax and constraints, and the meaning of exactRelatives/exactKeyword/exactRace. It also covers collectionFocus, collectionId, and extraParams. Even though not every parameter is individually described, the ones needing explanation are covered thoroughly.

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 clearly states it searches Ancestry historical records (census, vital, military, immigration…) plus optionally trees, stories, and photos, and identifies it as the full website search form. This distinguishes it from siblings like record (which fetches a specific record) and person (which handles individual profiles). The scope is unambiguous.

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?

Provides explicit search strategy: 'Start broad (name + birth year), then narrow.' Explains when to use collectionFocus (re-rank toward a country/ethnicity) vs collectionId (restrict to one collection) vs extraParams (collection-specific fields). It also describes how to tighten matching per field (exactName, firstNameMatch/lastNameMatch, exactRelatives, etc.) and references downstream tools (record.get, record.save_to_person). This gives clear when-to-use and how-to-use 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=false and destructiveHint=true, and the description lists remove_citation, remove_web_link, and unlink_repository, which are destructive operations, consistent with the annotation. It also adds workflow context like webLinkId coming from person.get. No contradiction; the description adds action-level behavior beyond 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?

The description is comprehensive but long; it uses a clear structure with a definition, a list of actions, and specific workflow pointers. It is front-loaded with the core concept. Though verbose, each sentence adds value, so it is acceptable.

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 has 12 actions and 26 parameters with no output schema, the description should explain each action's purpose and parameter implications. It lists actions but leaves many as self-explanatory, and it provides some hints (e.g., get_citation returns facts). However, details for actions like link_repository, update_citation, and add_web_link are not fully elaborated, making the definition incomplete for reliable 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 only 15%, and most parameters (url, date, note, page, email, phone, etc.) are not explained in the description. The description only hints at a few parameters (e.g., create_source requires title, create_citation requires sourceId and detail). This is insufficient compensation for the low schema coverage, leaving many parameters ambiguous.

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 begins by defining what a source versus a citation is, then lists the exact actions available. It clearly states the tool manages sources, repositories, citations, and web links, distinguishing it from siblings that handle persons, facts, or trees.

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 provides workflow guidance: create_source takes only title, then update_source fills details; create_citation needs sourceId and detail. It references fact.attach_citation and person.get, indicating how the tool fits the overall process. However, it does not explicitly state when to prefer this tool over a sibling or when not to use 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 already set destructiveHint=true, and the description meaningfully extends that by stating delete is PERMANENT, requires confirmName to match the exact tree name, and requires user confirmation first. It also discloses export's dual write-or-base64 behavior and import's wait-for-completion behavior, which are non-obvious operational details.

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 resource and packs all action semantics, prerequisites, and danger warnings into a compact, structured format. Every clause adds operational value and nothing is repeated or 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?

For a complex 8-action, 16-parameter tool with no output schema, the description covers action effects, required parameters, and unusual return behaviors such as export's base64 option and import's waiting behavior. It does not state what create, update, set_privacy, or delete return, which an agent may need for follow-up operations.

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 only 25% schema coverage, the description compensates by connecting actions to required parameters and clarifying the purpose of outPath, filePath, and confirmName. However, 'root* fields' is ambiguous about which root properties are actually required, and rights, isPublic, and searchable are left to inference.

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 identifies the resource as family trees owned by the user and enumerates eight specific actions, each with a short effect (e.g., 'get (home person, counts, quality stats)', 'export_gedcom (writes ZIP with .ged to outPath, or returns base64)'). This is clearly distinct from sibling tools like person, fact, and record, which operate on other resource types.

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 final sentence provides explicit per-action prerequisites: 'get/update/set_privacy/export_gedcom/delete need treeId; create needs name + root* fields; import_gedcom needs name + filePath.' It also gives a clear workflow warning for delete: confirm with the user and provide confirmName. It does not explicitly name sibling alternatives, but the resource scope and action list establish when to use this tool.

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