feat(ipa): Decouple property descriptions from API mechanics in IPA-117

ipa/general/0117.md

@@ -31,6 +31,29 @@ will promote clarity, completeness and consistency.
   - Descriptions **must** avoid company internal language conventions
   - Descriptions **should** prefer simple syntax that can easily be translated
     for non-English speakers
+- Descriptions **should** describe fields in terms meaningful to API consumers,
+  not in terms of API mechanics. Referencing other API-specific constructs
+  couples the description to tooling context that is not visible to end users of
+  generated clients and forces downstream tooling to override the text.
+
+  **Anti-pattern** (references an operation ID and endpoint path):
+
+  > Unique 24-hexadecimal digit string that identifies the organization that
+  > contains your projects. Use the
+  > [`/orgs`](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Organizations/operation/listOrganizations)
+  > endpoint to retrieve all organizations to which the authenticated user has
+  > access.
+
+  **Preferred** (consumer-facing, no API mechanics):
+
+  > Unique 24-hexadecimal digit string that identifies the organization that
+  > contains your projects.
+
+- When the same property appears in multiple polymorphic variants unified by
+  `oneOf` with a discriminator (see [IPA-125](0125.md)), that property's
+  description **should** be identical across variants. Variant-specific context
+  **should** be documented in the variant schema's own `description`, not by
+  diverging the property's description between variants.
 - See
   [Description Object](https://www.learnjsonschema.com/2020-12/meta-data/description/)
 - Documentation **may** link to external documentation when more in-depth