---
name: contribute-philanthropic-tools
description: Guide for external contributors and their AI agents to add modular tool .md files or curated philanthropic leads via pull request.
---

# Contribute a Modular Tool or Curated Lead to `philanthropic.tools`

`philanthropic.tools` is designed as an **open, modular Markdown repository** (`ariapbc/philanthropic.tools`) so domain researchers, foundation program officers, engineers, and their AI agents can collaborate via pull request.

## Invariants Enforced by CI (`npm run validate`)

1. **One Modular `.md` File Per Tool or Lead:** Place external tools under `tools/<category>/<slug>.md` and curated leads under `kb/leads/<domain>/<slug>.md`.
2. **Strictly Non-Custodial:** Every tool must set `custody_posture: non-custodial`. No pay-to-rank affiliate schemes or custodial wallets.
3. **Zero Precomputed Scores:** Never include `score`, `stars`, `rank`, or `impact_score` keys. Provide factual summaries, vehicle/fiscal-sponsor structure, and at least 2 concrete `diligence_pointers` for user agents to verify live.

## Authoring a New Modular Tool (`tools/<category>/<id>.md`)

```markdown
---
id: example-public-api
name: Example Public Registry API
category: registries-and-filings
kind_label: REST API
provider: Example Nonprofit Org
url: https://example.org/api
auth: None (Public)
custody_posture: non-custodial
summary: Concise one-sentence description of what an agent can verify or compose with this tool.
tags: [990, ein, verification]
---

## What This Affordance Provides
Explain what factual signal or non-custodial action this tool unlocks for an agent.

## How Agents Should Invoke & Compose It
Provide endpoint templates, URL patterns, or CLI/HTTP examples, plus edge cases (such as data lag or fiscal-sponsor parent EIN caveats).
```

## Validation & PR Checklist

1. Run `npm run validate` to check YAML frontmatter, cross-references, and non-custodial invariants.
2. Run `npm test && npm run build` to ensure static endpoints (`llms.txt`, `api/catalog.json`, `md/`) compile cleanly.
3. Open a pull request against `ariapbc/philanthropic.tools` citing primary public sources.